feat: Expose authenticated request context

Stainless-Generated-From: 6e370a57405066ad44066d88f375704812affb83

Author: kernel-internal[bot]

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 133
+configured_endpoints: 134

api.md

@@ -261,6 +261,16 @@ Methods:
 
 # Auth
 
+## Context
+
+Types:
+
+- <code><a href="./src/resources/auth/context.ts">AuthContext</a></code>
+
+Methods:
+
+- <code title="get /auth/context">client.auth.context.<a href="./src/resources/auth/context.ts">retrieve</a>() -> AuthContext</code>
+
 ## Connections
 
 Types:

src/resources/auth/auth.ts

@@ -21,14 +21,20 @@ import {
   SubmitFieldsRequest,
   SubmitFieldsResponse,
 } from './connections';
+import * as ContextAPI from './context';
+import { AuthContext, Context } from './context';
 
 export class Auth extends APIResource {
+  context: ContextAPI.Context = new ContextAPI.Context(this._client);
   connections: ConnectionsAPI.Connections = new ConnectionsAPI.Connections(this._client);
 }
 
+Auth.Context = Context;
 Auth.Connections = Connections;
 
 export declare namespace Auth {
+  export { Context as Context, type AuthContext as AuthContext };
+
   export {
     Connections as Connections,
     type LoginResponse as LoginResponse,

src/resources/auth/context.ts

@@ -0,0 +1,125 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+
+/**
+ * Inspect the identity and authorization context for the current request.
+ */
+export class Context extends APIResource {
+  /**
+   * Returns the authenticated principal, organization, credential scope, and
+   * effective request scope. The response is derived from the verified request
+   * context and does not expose credential secrets.
+   *
+   * @example
+   * ```ts
+   * const authContext = await client.auth.context.retrieve();
+   * ```
+   */
+  retrieve(options?: RequestOptions): APIPromise<AuthContext> {
+    return this._client.get('/auth/context', options);
+  }
+}
+
+/**
+ * The identity and authorization context resolved for the current request.
+ */
+export interface AuthContext {
+  authentication: AuthContext.Authentication;
+
+  /**
+   * The credential's maximum scope and the effective scope selected for this
+   * request. Future permission data can be added without changing scope semantics.
+   */
+  authorization: AuthContext.Authorization;
+
+  organization: AuthContext.Organization;
+
+  principal: AuthContext.Principal;
+}
+
+export namespace AuthContext {
+  export interface Authentication {
+    /**
+     * The API key ID when authenticated with an API key; null for session credentials.
+     */
+    credential_id: string | null;
+
+    /**
+     * The credential format used to authenticate the request.
+     */
+    method: 'api_key' | 'jwt';
+
+    /**
+     * The source classification resolved by authentication middleware.
+     */
+    source: 'api_key' | 'oauth' | 'dashboard';
+  }
+
+  /**
+   * The credential's maximum scope and the effective scope selected for this
+   * request. Future permission data can be added without changing scope semantics.
+   */
+  export interface Authorization {
+    /**
+     * A scope within the authenticated organization. A null project_id represents
+     * organization-wide scope.
+     */
+    credential_scope: Authorization.CredentialScope;
+
+    /**
+     * A scope within the authenticated organization. A null project_id represents
+     * organization-wide scope.
+     */
+    effective_scope: Authorization.EffectiveScope;
+  }
+
+  export namespace Authorization {
+    /**
+     * A scope within the authenticated organization. A null project_id represents
+     * organization-wide scope.
+     */
+    export interface CredentialScope {
+      /**
+       * The Kernel project ID, or null when the scope is organization-wide.
+       */
+      project_id: string | null;
+    }
+
+    /**
+     * A scope within the authenticated organization. A null project_id represents
+     * organization-wide scope.
+     */
+    export interface EffectiveScope {
+      /**
+       * The Kernel project ID, or null when the scope is organization-wide.
+       */
+      project_id: string | null;
+    }
+  }
+
+  export interface Organization {
+    /**
+     * The authenticated Kernel organization ID.
+     */
+    id: string;
+  }
+
+  export interface Principal {
+    /**
+     * The API key ID for API-key principals or user ID for user principals.
+     */
+    id: string;
+
+    /**
+     * The kind of principal authenticated for the request.
+     */
+    type: 'api_key' | 'user';
+  }
+}
+
+export declare namespace Context {
+  export { type AuthContext as AuthContext };
+}

src/resources/auth/index.ts

@@ -20,3 +20,4 @@ export {
   type ManagedAuthsOffsetPagination,
   type ManagedAuthTimelineEventsOffsetPagination,
 } from './connections';
+export { Context, type AuthContext } from './context';

tests/api-resources/auth/context.test.ts

@@ -0,0 +1,22 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import Kernel from '@onkernel/sdk';
+
+const client = new Kernel({
+  apiKey: 'My API Key',
+  baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010',
+});
+
+describe('resource context', () => {
+  // Mock server tests are disabled
+  test.skip('retrieve', async () => {
+    const responsePromise = client.auth.context.retrieve();
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+});