@eduwork/dsh-oidc 0.1.0-alpha.11

package/lib/provider/transform-adapter.js

@@ -0,0 +1,65 @@
+/** Delegate one enterprise route while applying capabilities contributed by replaceable feature plugins. */
+export class TransformingEnterpriseAdapter {
+  constructor(inner, transforms, modelPolicy = () => ({})) {
+    this.inner = inner
+    this.transforms = transforms
+    this.modelPolicy = modelPolicy
+  }
+
+  providerInfo(provider) { return this.inner.providerInfo(provider) }
+  providerRetryPolicy(provider) { return this.inner.providerRetryPolicy(provider) }
+
+  async listModels(provider) {
+    const models = await this.inner.listModels(provider)
+    return models.map(model => ({
+      ...model,
+      inputModalities: this.transforms.capabilities(provider, model.id, model.inputModalities),
+    }))
+  }
+
+  async resolveModel(provider, model, signal) {
+    return this.decorateModel(provider, model, await this.inner.resolveModel(provider, model, signal))
+  }
+
+  decorateModel(provider, model, resolved) {
+    const decorated = {
+      ...resolved,
+      inputModalities: this.transforms.capabilities(provider, model, resolved.inputModalities),
+    }
+    const policy = this.modelPolicy(provider, model)
+    if (policy.reasoning === false || policy.supportsReasoningEffort !== false) return decorated
+    const { reasoning: _unsupportedReasoningEfforts, ...thinkingOnly } = decorated
+    return thinkingOnly
+  }
+
+  async prepareCall(provider, model, signal) {
+    const prepared = typeof this.inner.prepareCall === 'function'
+      ? await this.inner.prepareCall(provider, model, signal)
+      : { model: await this.inner.resolveModel(provider, model, signal), stream: options => this.inner.stream(options) }
+    return {
+      model: this.decorateModel(provider, model, prepared.model),
+      stream: options => this.streamPrepared(options, prepared),
+    }
+  }
+
+  async * streamPrepared(options, prepared) {
+    const nativeModelInfo = prepared.model
+    let request = options
+    const policy = this.modelPolicy(options.provider, options.model)
+    if (policy.reasoning === false) {
+      request = { ...options, reasoningEffort: 'off' }
+    } else if (policy.supportsReasoningEffort === false) {
+      const { reasoningEffort: _unsupportedReasoningEffort, ...withoutEffort } = options
+      request = withoutEffort
+    }
+    yield* prepared.stream(await this.transforms.apply(request, nativeModelInfo))
+  }
+
+  async * stream(options) {
+    const prepared = typeof this.inner.prepareCall === 'function'
+      ? await this.inner.prepareCall(options.provider, options.model, options.signal)
+      : { model: await this.inner.resolveModel(options.provider, options.model, options.signal), stream: request => this.inner.stream(request) }
+    yield* this.streamPrepared(options, prepared)
+  }
+}
+

package/lib/provider/transforms.js

@@ -0,0 +1,59 @@
+import { Service } from '@deepseek-ai/cordis'
+
+function routeKey(provider, model) {
+  return `${provider}\u0000${model ?? '*'}`
+}
+
+function normalizedModalities(inputModalities) {
+  return [...new Set(inputModalities ?? [])]
+}
+
+/**
+ * Stable extension seam for plugins that add a capability to an enterprise
+ * route without replacing the route owner or mutating the durable transcript.
+ */
+export class EnterpriseModelTransforms extends Service {
+  constructor(ctx) {
+    super(ctx, 'enterpriseTransforms')
+    this.entries = new Map()
+  }
+
+  register({ provider, model, inputModalities = [], when = () => true, transform }) {
+    if (typeof provider !== 'string' || provider.length === 0) throw new Error('enterprise transform provider is required')
+    if (model !== undefined && (typeof model !== 'string' || model.length === 0)) throw new Error('enterprise transform model must be a non-empty string when provided')
+    if (typeof when !== 'function') throw new Error('enterprise transform condition must be a function')
+    if (typeof transform !== 'function') throw new Error('enterprise transform must be a function')
+    const key = routeKey(provider, model)
+    if (this.entries.has(key)) throw new Error(`enterprise transform already registered for ${provider}/${model ?? '*'}`)
+    const entry = Object.freeze({ provider, model, inputModalities: normalizedModalities(inputModalities), when, transform })
+    this.entries.set(key, entry)
+    this.ctx.emit('llm/adapters-updated')
+    return () => {
+      if (this.entries.get(key) !== entry) return
+      this.entries.delete(key)
+      this.ctx.emit('llm/adapters-updated')
+    }
+  }
+
+  matching(provider, model, nativeInputModalities) {
+    const native = normalizedModalities(nativeInputModalities)
+    return [
+      this.entries.get(routeKey(provider, undefined)),
+      this.entries.get(routeKey(provider, model)),
+    ].filter(entry => entry !== undefined && entry.when({ provider, model, inputModalities: native }))
+  }
+
+  capabilities(provider, model, inputModalities) {
+    const extra = this.matching(provider, model, inputModalities).flatMap(entry => entry.inputModalities)
+    return normalizedModalities([...(inputModalities ?? []), ...extra])
+  }
+
+  async apply(options, nativeModelInfo) {
+    let transformed = options
+    for (const entry of this.matching(options.provider, options.model, nativeModelInfo?.inputModalities)) {
+      transformed = await entry.transform(transformed, nativeModelInfo)
+    }
+    return transformed
+  }
+}
+

package/lib/typert-schemas.js

@@ -0,0 +1,84 @@
+import { z } from 'zod'
+
+const pkg = '@eduwork/dsh-oidc'
+export const profileIdSchema = z.string().min(1).max(64)
+export const reconcileOptionsSchema = z.object({ allowProvision: z.boolean().optional() }).strict()
+export const baseURLSchema = z.string().min(1).max(2048)
+export const modelCatalogModeSchema = z.enum(['discovery', 'manual'])
+
+const brandSchema = z.object({
+  productName: z.string().optional(), organizationName: z.string().optional(), mark: z.string().optional(),
+  logoURL: z.string().optional(), primaryColor: z.string().optional(), loginTitle: z.string().optional(),
+  loginDescription: z.string().optional(), supportURL: z.string().optional(),
+}).strict()
+
+const publicProfileSchema = z.object({
+  id: z.string(), displayName: z.string(), organization: z.string(), brand: brandSchema,
+  credentialRef: z.string(),
+  provider: z.object({
+    id: z.string(), displayName: z.string(),
+    models: z.array(z.object({ id: z.string(), name: z.string(), input: z.array(z.enum(['text', 'image'])) }).strict()),
+  }).strict(),
+}).strict()
+
+const accountSchema = z.object({
+  profileID: z.string(), displayName: z.string(), organization: z.string(), state: z.string(),
+  userName: z.string().optional(), affiliation: z.string().optional(), accessExpiresAt: z.string().optional(),
+  credentialRef: z.string(), credentialReady: z.boolean(), credentialState: z.string().optional(),
+  capabilities: z.array(z.string()).optional(),
+}).strict()
+
+export const runtimeModelSchema = z.object({
+  id: z.string().min(1).max(256), name: z.string().max(256).optional(),
+  upstreamModelID: z.string().max(256).optional(), contextWindow: z.number().int().positive().optional(),
+  maxTokens: z.number().int().positive().optional(),
+  input: z.array(z.enum(['text', 'image', 'audio', 'video'])).optional(),
+  reasoning: z.boolean().optional(), reasoningEfforts: z.record(z.string(), z.string().nullable()).optional(),
+  compat: z.record(z.string(), z.unknown()).optional(),
+}).strict()
+
+export const runtimeModelsSchema = z.array(runtimeModelSchema).max(128)
+
+const managementProfileSchema = z.object({
+  id: z.string(), displayName: z.string(), organization: z.string(), baseURL: z.string(),
+  builtIn: z.boolean(), configured: z.boolean(), enabled: z.boolean(), providerID: z.string(),
+  runtime: z.object({
+    displayName: z.string(), modelSource: z.string().optional(), reasoning: z.string().optional(),
+    defaultContextWindow: z.number().int().positive().optional(), defaultMaxTokens: z.number().int().positive().optional(),
+    compat: z.record(z.string(), z.unknown()).optional(), models: runtimeModelsSchema,
+  }).strict(),
+}).strict()
+
+export const configurationResult = Object.freeze({
+  mode: 'strict', typeSymbol: `${pkg}#Configuration`,
+  schema: z.object({ schemaVersion: z.literal('dsh-oidc/v1alpha1'), uiMode: z.enum(['standard', 'models-only', 'external']), profiles: z.array(publicProfileSchema) }).strict(),
+})
+
+export const managementResult = Object.freeze({
+  mode: 'strict', typeSymbol: `${pkg}#ManagementConfiguration`,
+  schema: z.object({
+    schemaVersion: z.literal('dsh-oidc/management/v1alpha1'), mode: z.enum(['profile', 'native']),
+    activeProfileID: z.string(), restartRequired: z.boolean(),
+    capabilities: z.object({ manageProfiles: z.boolean(), manageModels: z.boolean(), restart: z.boolean() }).strict(),
+    profiles: z.array(managementProfileSchema),
+  }).strict(),
+})
+
+export const restartResult = Object.freeze({
+  mode: 'strict', typeSymbol: `${pkg}#RestartResult`,
+  schema: z.object({ restarting: z.literal(true) }).strict(),
+})
+
+export const accountResult = Object.freeze({ mode: 'strict', typeSymbol: `${pkg}#AccountStatus`, schema: accountSchema })
+
+export const beginResult = Object.freeze({
+  mode: 'strict', typeSymbol: `${pkg}#BeginResult`,
+  schema: z.union([
+    z.object({ mode: z.literal('redirect'), authorizationURL: z.string().url() }).strict(),
+    z.object({ mode: z.literal('completed'), status: accountSchema }).strict(),
+  ]),
+})
+
+export function jsonParameter(name, schema, typeSymbol) {
+  return Object.freeze({ name, wire: name, source: 'json', codec: Object.freeze({ mode: 'strict', typeSymbol, schema }) })
+}

package/lib/typert.host.js

@@ -0,0 +1,38 @@
+import {
+  accountResult, baseURLSchema, beginResult, configurationResult, jsonParameter, managementResult,
+  modelCatalogModeSchema, profileIdSchema, reconcileOptionsSchema, restartResult, runtimeModelsSchema,
+} from './typert-schemas.js'
+
+const pkg = '@eduwork/dsh-oidc'
+const source = { file: 'lib/index.js', line: 1, column: 1 }
+const profile = () => jsonParameter('profileID', profileIdSchema, `${pkg}#ProfileID`)
+const options = () => jsonParameter('options', reconcileOptionsSchema, `${pkg}#ReconcileOptions`)
+const baseURL = () => jsonParameter('baseURL', baseURLSchema, `${pkg}#BaseURL`)
+const modelMode = () => jsonParameter('modelMode', modelCatalogModeSchema, `${pkg}#ModelCatalogMode`)
+const models = () => jsonParameter('models', runtimeModelsSchema, `${pkg}#RuntimeModels`)
+const descriptor = (method, parameters, result) => ({
+  id: `${pkg}#oidcAccounts/${method}`, service: 'oidcAccounts', namespace: 'oidcAccounts', method,
+  invocation: { kind: 'direct' }, parameters, result, sourceLocation: source,
+})
+
+export const TYPERT = {
+  package: pkg, face: 'host', schemas: [],
+  invocations: [
+    descriptor('configuration', [], configurationResult),
+    descriptor('status', [profile()], accountResult),
+    descriptor('begin', [profile()], beginResult),
+    descriptor('reconcile', [profile(), options()], accountResult),
+    descriptor('logout', [profile()], accountResult),
+    descriptor('management', [], managementResult),
+    descriptor('activate', [profile()], managementResult),
+    descriptor('configure', [profile()], managementResult),
+    descriptor('addCustom', [baseURL()], managementResult),
+    descriptor('updateCustom', [profile(), baseURL()], managementResult),
+    descriptor('removeProfile', [profile()], managementResult),
+    descriptor('configureModels', [profile(), modelMode(), models()], managementResult),
+    descriptor('restart', [], restartResult),
+  ],
+  model: { services: [], events: [], objects: [] },
+}
+
+export default TYPERT

package/lib/typert.remote-client.js

@@ -0,0 +1,37 @@
+import {
+  accountResult, baseURLSchema, beginResult, configurationResult, jsonParameter, managementResult,
+  modelCatalogModeSchema, profileIdSchema, reconcileOptionsSchema, restartResult, runtimeModelsSchema,
+} from './typert-schemas.js'
+
+const pkg = '@eduwork/dsh-oidc'
+const source = { file: 'lib/index.js', line: 1, column: 1 }
+const profile = () => jsonParameter('profileID', profileIdSchema, `${pkg}#ProfileID`)
+const options = () => jsonParameter('options', reconcileOptionsSchema, `${pkg}#ReconcileOptions`)
+const baseURL = () => jsonParameter('baseURL', baseURLSchema, `${pkg}#BaseURL`)
+const modelMode = () => jsonParameter('modelMode', modelCatalogModeSchema, `${pkg}#ModelCatalogMode`)
+const models = () => jsonParameter('models', runtimeModelsSchema, `${pkg}#RuntimeModels`)
+const descriptor = (method, parameters, result) => ({
+  id: `${pkg}#oidcAccounts/${method}`, service: 'oidcAccounts', namespace: 'oidcAccounts', method,
+  invocation: { kind: 'direct' }, parameters, result, sourceLocation: source,
+})
+
+export const TYPERT_REMOTE = {
+  package: pkg,
+  descriptors: [
+    descriptor('configuration', [], configurationResult),
+    descriptor('status', [profile()], accountResult),
+    descriptor('begin', [profile()], beginResult),
+    descriptor('reconcile', [profile(), options()], accountResult),
+    descriptor('logout', [profile()], accountResult),
+    descriptor('management', [], managementResult),
+    descriptor('activate', [profile()], managementResult),
+    descriptor('configure', [profile()], managementResult),
+    descriptor('addCustom', [baseURL()], managementResult),
+    descriptor('updateCustom', [profile(), baseURL()], managementResult),
+    descriptor('removeProfile', [profile()], managementResult),
+    descriptor('configureModels', [profile(), modelMode(), models()], managementResult),
+    descriptor('restart', [], restartResult),
+  ],
+}
+
+export default TYPERT_REMOTE

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@eduwork/dsh-oidc",
+  "version": "0.1.0-alpha.11",
+  "description": "Standards-based OIDC identity, enterprise API-key binding, declarative branding, and OpenAI-compatible model integration for DeepSeek Harness",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "oidc",
+    "openid-connect",
+    "enterprise",
+    "sso"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./profile": "./lib/profile.js",
+    "./oidc": "./lib/oidc.js",
+    "./provider": "./lib/provider/index.js",
+    "./transforms": "./lib/provider/transforms.js",
+    "./typert": "./lib/typert.host.js",
+    "./remote": "./lib/typert.remote-client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "cordis.patch.yml",
+    "lib/**/*.js",
+    "docs/**/*.md",
+    "examples/**/*.json",
+    "schema/**/*.json",
+    "protocol/openapi.yaml",
+    "README.md",
+    "README.en.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "THIRD_PARTY_NOTICES.en.md",
+    "CHANGELOG.md",
+    "CHANGELOG.en.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-models",
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-theme"
+      ],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "scripts": {
+    "build:host": "node scripts/build-host.mjs",
+    "build:client": "tsdown",
+    "build": "npm run build:host && npm run build:client",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage",
+    "check:schemas": "node scripts/check-schemas.mjs",
+    "check:secrets": "node scripts/check-secrets.mjs",
+    "check:licenses": "node scripts/check-licenses.mjs",
+    "check:docs": "node scripts/check-doc-links.mjs",
+    "check:build": "node scripts/smoke-build.mjs",
+    "check": "npm run typecheck && npm run build && npm run check:build && npm test && npm run check:schemas && npm run check:docs && npm run check:secrets && npm run check:licenses && npm pack --dry-run",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freedomkk-qfeng/dsh-oidc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/freedomkk-qfeng/dsh-oidc/issues"
+  },
+  "homepage": "https://github.com/freedomkk-qfeng/dsh-oidc#readme",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-api-remotes": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-settings-models": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-theme": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-credentials": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-launch-environment": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm-pi-ai": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-settings": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.2-alpha.2",
+    "@earendil-works/pi-ai": "^0.84.2",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.28",
+    "ajv": "^8.17.1",
+    "tsdown": "0.22.14",
+    "typescript": "^5.9.3",
+    "yaml": "^2.8.1"
+  }
+}

package/protocol/openapi.yaml

@@ -0,0 +1,257 @@
+openapi: 3.1.0
+info:
+  title: dsh-oidc Worker User Center Key Binding API
+  version: 1.0.0
+  description: >-
+    The fixed worker-user-center-v1 protocol used by dsh-oidc to exchange an
+    OIDC Bearer access token for a short-lived or revocable model runtime
+    credential. Endpoint paths and wire field names are deliberately not
+    configurable. See docs/key-binding-protocol.md for normative requirements.
+  license:
+    name: MIT
+    identifier: MIT
+servers:
+  - url: https://ai.example.edu/api/worker/v1
+    description: Example baseURL from an Enterprise Profile
+security:
+  - oidcAccessToken: []
+paths:
+  /bootstrap:
+    get:
+      operationId: bootstrap
+      summary: Read subject-independent integration state and credential lifecycle state
+      responses:
+        '200':
+          description: Current provider and runtime credential state
+          headers:
+            Cache-Control:
+              schema: { type: string }
+              description: MUST contain no-store
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/BootstrapResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '5XX': { $ref: '#/components/responses/ServerError' }
+  /runtime-credential/provision:
+    post:
+      operationId: provisionRuntimeCredential
+      summary: Provision and return a runtime credential for the authenticated subject
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/RuntimeCredentialRequest' }
+      responses:
+        '200': { $ref: '#/components/responses/RuntimeCredential' }
+        '201': { $ref: '#/components/responses/RuntimeCredential' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '409': { $ref: '#/components/responses/Conflict' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '5XX': { $ref: '#/components/responses/ServerError' }
+  /runtime-credential/resolve:
+    post:
+      operationId: resolveRuntimeCredential
+      summary: Resolve the active runtime credential for the authenticated subject
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/RuntimeCredentialRequest' }
+      responses:
+        '200': { $ref: '#/components/responses/RuntimeCredential' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '5XX': { $ref: '#/components/responses/ServerError' }
+  /runtime-credential/renew:
+    post:
+      operationId: renewRuntimeCredential
+      summary: Rotate an expiring or expired runtime credential
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              allOf:
+                - $ref: '#/components/schemas/RuntimeCredentialRequest'
+                - type: object
+                  required: [api_key_id]
+      responses:
+        '200': { $ref: '#/components/responses/RuntimeCredential' }
+        '201': { $ref: '#/components/responses/RuntimeCredential' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '5XX': { $ref: '#/components/responses/ServerError' }
+components:
+  securitySchemes:
+    oidcAccessToken:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT or opaque OIDC access token
+      description: >-
+        Access token issued to the public OIDC client declared in the matching
+        Enterprise Profile. The server validates issuer, audience, expiry,
+        required scopes, and the authenticated subject.
+  parameters:
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      required: true
+      description: Opaque UUID generated for one logical mutating operation.
+      schema:
+        type: string
+        format: uuid
+  schemas:
+    BootstrapResponse:
+      type: object
+      additionalProperties: false
+      required: [provider, capabilities, runtime_credential]
+      properties:
+        protocol_version:
+          type: string
+          const: worker-user-center/v1
+          description: Optional during v1 adoption; if present it MUST equal this value.
+        subject:
+          $ref: '#/components/schemas/InformationalSubject'
+        provider:
+          type: object
+          additionalProperties: false
+          required: [id]
+          properties:
+            id:
+              type: string
+              pattern: '^[a-z][a-z0-9-]{0,63}$'
+        capabilities:
+          type: array
+          maxItems: 256
+          uniqueItems: true
+          items: { type: string, minLength: 1, maxLength: 128 }
+        runtime_credential:
+          $ref: '#/components/schemas/RuntimeCredentialState'
+    InformationalSubject:
+      type: object
+      additionalProperties: true
+      description: >-
+        Optional management-plane display data. dsh-oidc MUST NOT use it to
+        replace the identity established by the OIDC ID Token and UserInfo.
+      properties:
+        sub: { type: string }
+        name: { type: string }
+        affiliation: { type: string }
+    RuntimeCredentialState:
+      type: object
+      additionalProperties: false
+      required: [status]
+      properties:
+        status:
+          enum: [missing, active, expiring, expired, suspended, unavailable]
+        api_key_id:
+          type: string
+          minLength: 1
+          maxLength: 256
+        expires_at:
+          type: string
+          format: date-time
+        provisioning:
+          type: object
+          additionalProperties: false
+          properties:
+            allowed: { type: boolean }
+            reason: { type: string, maxLength: 500 }
+    RuntimeCredentialRequest:
+      type: object
+      additionalProperties: false
+      required: [provider_id]
+      properties:
+        provider_id:
+          type: string
+          pattern: '^[a-z][a-z0-9-]{0,63}$'
+        api_key_id:
+          type: string
+          minLength: 1
+          maxLength: 256
+    RuntimeCredentialResponse:
+      type: object
+      additionalProperties: false
+      required: [provider_id, api_key, status]
+      properties:
+        provider_id:
+          type: string
+          pattern: '^[a-z][a-z0-9-]{0,63}$'
+        api_key:
+          type: string
+          minLength: 1
+          maxLength: 16384
+          description: Secret value. It MUST appear only in this TLS response and MUST NOT be logged.
+        api_key_id:
+          type: string
+          minLength: 1
+          maxLength: 256
+        status:
+          const: active
+        expires_at:
+          type: string
+          format: date-time
+    Problem:
+      type: object
+      additionalProperties: true
+      required: [type, title, status]
+      properties:
+        type: { type: string, format: uri-reference }
+        title: { type: string }
+        status: { type: integer, minimum: 400, maximum: 599 }
+        detail: { type: string }
+        instance: { type: string, format: uri-reference }
+        code: { type: string, description: Stable machine-readable service code }
+  responses:
+    RuntimeCredential:
+      description: Active runtime credential
+      headers:
+        Cache-Control:
+          schema: { type: string }
+          description: MUST contain no-store
+        Pragma:
+          schema: { type: string }
+          description: SHOULD be no-cache for compatibility
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/RuntimeCredentialResponse' }
+    BadRequest:
+      description: Invalid request
+      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
+    Unauthorized:
+      description: Missing, invalid, expired, or wrong-audience access token
+      headers:
+        WWW-Authenticate: { schema: { type: string } }
+      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
+    Forbidden:
+      description: Authenticated subject lacks the required scope or organization entitlement
+      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
+    NotFound:
+      description: Requested runtime credential does not exist
+      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
+    Conflict:
+      description: Idempotency conflict or incompatible credential lifecycle state
+      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
+    RateLimited:
+      description: Rate limit exceeded
+      headers:
+        Retry-After: { schema: { type: string } }
+      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
+    ServerError:
+      description: Server-side failure with no secret material
+      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }