@substrat-run/contracts 0.158.0 → 0.159.0

package/dist/auth-diagnostics.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Credential-free authentication diagnostics shared by providers, hosts and log readers.
+ * No runtime imports: the platform entry bundles this independently of the vertical.
+ * A diagnostic describes a check, never grants authority. Unknown fields are discarded
+ * on both write and read; tokens, claims, identities and exception messages have no slot.
+ */
+export declare const AUTH_CHECK_STAGES: readonly ['bearer', 'session', 'mcp-audience', 'mcp-caller'];
+export declare const AUTH_CHECK_OUTCOMES: readonly ['accepted', 'refused', 'absent', 'error'];
+export declare const AUTH_CHECK_REASONS: readonly ['verified', 'session-invalid', 'credential-missing', 'discovery-failed', 'key-resolution-failed', 'token-expired', 'token-not-active', 'issuer-invalid', 'audience-invalid', 'claims-invalid', 'signature-invalid', 'token-invalid', 'verification-failed', 'subject-missing', 'assertion-not-access-token', 'delegation-refused', 'token-not-for-app', 'resource-mismatch', 'caller-resolved', 'caller-refused', 'caller-error'];
+export interface AuthCheck {
+    stage: (typeof AUTH_CHECK_STAGES)[number];
+    outcome: (typeof AUTH_CHECK_OUTCOMES)[number];
+    reason: (typeof AUTH_CHECK_REASONS)[number];
+}
+export declare const AUTH_CHECK_CAP = 16;
+export interface AuthRecording {
+    authChecks?: AuthCheck[];
+    authChecksDropped?: number;
+}
+/** Registered across bundled copies; the host supplies a request-local recorder. */
+export declare const AUTH_DIAGNOSTICS_KEY: unique symbol;
+export interface AuthDiagnosticsSink {
+    record(check: AuthCheck): void;
+}
+/** Copy only the bounded vocabulary, including when called from untyped code. */
+export declare function authCheckOf(value: unknown): AuthCheck | undefined;
+/** Old lines and unrecognised future entries read as unrecorded, never as success. */
+export declare function authChecksOf(value: unknown): AuthCheck[];
+export declare function tallyAuthCheck(record: AuthRecording, value: AuthCheck): void;
+/** Best effort. No host, an old host, or a broken sink must not change authentication. */
+export declare function recordAuthCheck(check: AuthCheck): void;
+//# sourceMappingURL=auth-diagnostics.d.ts.map

package/dist/auth-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-diagnostics.d.ts","sourceRoot":"","sources":["../src/auth-diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,YAAI,QAAQ,EAAE,SAAS,EAAE,cAAc,EAAE,YAAY,CAAU,CAAC;AAC9F,eAAO,MAAM,mBAAmB,YAAI,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAC;AACvF,eAAO,MAAM,kBAAkB,YAC7B,UAAU,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,uBAAuB,EAChG,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,kBAAkB,EACzE,gBAAgB,EAAE,mBAAmB,EAAE,eAAe,EAAE,qBAAqB,EAC7E,iBAAiB,EAAE,4BAA4B,EAAE,oBAAoB,EAAE,mBAAmB,EAC1F,mBAAmB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,cAAc,CAChE,CAAC;AAEX,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,EAAE,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,EAAE,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,eAA0C,CAAC;AAC5E,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CAChC;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAOjE;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,EAAE,CAMxD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAM5E;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAStD"}

package/dist/auth-diagnostics.js

@@ -0,0 +1,62 @@
+/**
+ * Credential-free authentication diagnostics shared by providers, hosts and log readers.
+ * No runtime imports: the platform entry bundles this independently of the vertical.
+ * A diagnostic describes a check, never grants authority. Unknown fields are discarded
+ * on both write and read; tokens, claims, identities and exception messages have no slot.
+ */
+export const AUTH_CHECK_STAGES = ['bearer', 'session', 'mcp-audience', 'mcp-caller'];
+export const AUTH_CHECK_OUTCOMES = ['accepted', 'refused', 'absent', 'error'];
+export const AUTH_CHECK_REASONS = [
+    'verified', 'session-invalid', 'credential-missing', 'discovery-failed', 'key-resolution-failed',
+    'token-expired', 'token-not-active', 'issuer-invalid', 'audience-invalid',
+    'claims-invalid', 'signature-invalid', 'token-invalid', 'verification-failed',
+    'subject-missing', 'assertion-not-access-token', 'delegation-refused', 'token-not-for-app',
+    'resource-mismatch', 'caller-resolved', 'caller-refused', 'caller-error',
+];
+export const AUTH_CHECK_CAP = 16;
+/** Registered across bundled copies; the host supplies a request-local recorder. */
+export const AUTH_DIAGNOSTICS_KEY = Symbol.for('substrat.auth-diagnostics');
+/** Copy only the bounded vocabulary, including when called from untyped code. */
+export function authCheckOf(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const v = value;
+    if (!AUTH_CHECK_STAGES.includes(v.stage)
+        || !AUTH_CHECK_OUTCOMES.includes(v.outcome)
+        || !AUTH_CHECK_REASONS.includes(v.reason))
+        return undefined;
+    return { stage: v.stage, outcome: v.outcome, reason: v.reason };
+}
+/** Old lines and unrecognised future entries read as unrecorded, never as success. */
+export function authChecksOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.slice(0, AUTH_CHECK_CAP).flatMap((v) => {
+        const check = authCheckOf(v);
+        return check ? [check] : [];
+    });
+}
+export function tallyAuthCheck(record, value) {
+    const check = authCheckOf(value);
+    if (!check)
+        return;
+    const checks = record.authChecks ??= [];
+    if (checks.length < AUTH_CHECK_CAP)
+        checks.push(check);
+    else
+        record.authChecksDropped = (record.authChecksDropped ?? 0) + 1;
+}
+/** Best effort. No host, an old host, or a broken sink must not change authentication. */
+export function recordAuthCheck(check) {
+    try {
+        const safe = authCheckOf(check);
+        if (!safe)
+            return;
+        const sink = globalThis[AUTH_DIAGNOSTICS_KEY];
+        sink?.record(safe);
+    }
+    catch {
+        // Observability never decides whether a caller is admitted.
+    }
+}
+//# sourceMappingURL=auth-diagnostics.js.map

package/dist/auth-diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-diagnostics.js","sourceRoot":"","sources":["../src/auth-diagnostics.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/contracts",
-  "version": "0.158.0",
+  "version": "0.159.0",
   "description": "Substrat kernel contract schemas — Zod is the source of truth (master plan D-22); OAS/JSON Schema are emitted artifacts",
   "license": "Apache-2.0",
   "repository": {
@@ -37,6 +37,10 @@
       "types": "./dist/assistant-stream.d.ts",
       "default": "./dist/assistant-stream.js"
     },
+    "./auth-diagnostics": {
+      "types": "./dist/auth-diagnostics.d.ts",
+      "default": "./dist/auth-diagnostics.js"
+    },
     "./trace-sink": {
       "types": "./dist/trace-sink.d.ts",
       "default": "./dist/trace-sink.js"