@lucern/contracts 0.3.0-alpha.16 → 0.3.0-alpha.17

package/CHANGELOG.md

@@ -8,3 +8,6 @@ All notable changes to `@lucern/contracts` are tracked in this repository.
 
 ## [0.3.0-alpha.7] - 2026-05-03
 - Rebuild the coherent Lucern package line after Campaign 1 SDK hardening fixes.
+
+## [0.3.0-alpha.17] - 2026-05-19
+- Release notes pending.

package/dist/auth-context.contract.js

@@ -18,7 +18,7 @@ var SESSION_LIFECYCLE_STATUSES = [
   "revoked"
 ];
 function inferSessionPrincipalType(principalId) {
-  if (principalId.startsWith("user:")) {
+  if (/^user_[A-Za-z0-9]+$/.test(principalId)) {
     return "human";
   }
   if (principalId.startsWith("agent:")) {

package/dist/auth-context.contract.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/auth.contract.ts"],"names":[],"mappings":";AAgBO,IAAM,kBAAA,GAAqB;AAAA,EAChC,kBAAA;AAAA,EACA,mBAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACF;AAGO,IAAM,uBAAA,GAA0B;AAAA,EACrC,OAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF;AAGO,IAAM,0BAAA,GAA6B;AAAA,EACxC,QAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF;AA2CO,SAAS,0BACd,WAAA,EACsB;AACtB,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,OAAO,CAAA,EAAG;AACnC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IACE,YAAY,UAAA,CAAW,WAAW,KAClC,WAAA,CAAY,UAAA,CAAW,kBAAkB,CAAA,EACzC;AACA,IAAA,OAAO,iBAAA;AAAA,EACT;AACA,EAAA,OAAO,SAAA;AACT;AAEO,SAAS,yBAAyB,IAAA,EAMF;AACrC,EAAA,IAAI,IAAA,CAAK,eAAA,IAAmB,IAAA,CAAK,eAAA,CAAgB,SAAS,CAAA,EAAG;AAC3D,IAAA,OAAO,CAAC,GAAG,IAAA,CAAK,eAAe,CAAA;AAAA,EACjC;AACA,EAAA,IAAI,CAAC,KAAK,WAAA,EAAa;AACrB,IAAA;AAAA,EACF;AACA,EAAA,OAAO;AAAA,IACL;AAAA,MACE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,aAAA,EACE,IAAA,CAAK,eAAA,IAAmB,yBAAA,CAA0B,KAAK,WAAW,CAAA;AAAA,MACpE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,QAAQ,IAAA,CAAK;AAAA;AACf,GACF;AACF;AAEO,SAAS,cACd,eAAA,EACoB;AACpB,EAAA,IAAI,CAAC,eAAA,IAAmB,eAAA,CAAgB,MAAA,KAAW,CAAA,EAAG;AACpD,IAAA;AAAA,EACF;AACA,EAAA,OAAO,eAAA,CAAgB,eAAA,CAAgB,MAAA,GAAS,CAAC,CAAA,EAAG,WAAA;AACtD","file":"auth-context.contract.js","sourcesContent":["/**\n * @lucern/contracts — auth (canonical support contract)\n *\n * Consolidated flat support surface for Lucern authentication:\n *   - Session primitives (auth modes, principal types, lifecycle)\n *   - AuthContext shape + McpTransportKind + LucernSdkClient alias\n *\n * Consolidated from src/auth-session.contract.ts and src/auth-context.contract.ts\n * in EK-16 T1 PR 3a. Compat shims remain at both old paths until Lucern 1.0.0 (D12).\n */\n\n// =============================================================================\n// SESSION PRIMITIVES\n// (Formerly src/auth-session.contract.ts)\n// =============================================================================\n\nexport const SESSION_AUTH_MODES = [\n  \"interactive_user\",\n  \"service_principal\",\n  \"tenant_api_key\",\n  \"session_token\",\n] as const;\nexport type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];\n\nexport const SESSION_PRINCIPAL_TYPES = [\n  \"human\",\n  \"service\",\n  \"agent\",\n  \"group\",\n  \"external_viewer\",\n] as const;\nexport type SessionPrincipalType = (typeof SESSION_PRINCIPAL_TYPES)[number];\n\nexport const SESSION_LIFECYCLE_STATUSES = [\n  \"active\",\n  \"expired\",\n  \"revoked\",\n] as const;\nexport type SessionLifecycleStatus =\n  (typeof SESSION_LIFECYCLE_STATUSES)[number];\n\nexport type SessionDelegationHop = {\n  principalId: string;\n  principalType: SessionPrincipalType;\n  authMode?: SessionAuthMode;\n  sessionId?: string;\n  delegatedAt?: number;\n  reason?: string;\n};\n\nexport type SessionAuditOutcome =\n  | \"accepted\"\n  | \"rejected\"\n  | \"revoked\"\n  | \"expired\";\n\nexport type SessionAuditEnvelope = {\n  sessionId: string;\n  authMode: SessionAuthMode;\n  principalId: string;\n  principalType: SessionPrincipalType;\n  tenantId: string;\n  workspaceId?: string;\n  apiKeyId?: string;\n  scopes: readonly string[];\n  roles?: readonly string[];\n  delegationChain?: readonly SessionDelegationHop[];\n  sourceSessionId?: string;\n  expiresAt?: number;\n  request?: {\n    endpoint?: string;\n    method?: string;\n    correlationId?: string;\n  };\n  result?: {\n    outcome: SessionAuditOutcome;\n    reason?: string;\n  };\n};\n\nexport function inferSessionPrincipalType(\n  principalId: string\n): SessionPrincipalType {\n  if (principalId.startsWith(\"user:\")) {\n    return \"human\";\n  }\n  if (principalId.startsWith(\"agent:\")) {\n    return \"agent\";\n  }\n  if (principalId.startsWith(\"group:\")) {\n    return \"group\";\n  }\n  if (\n    principalId.startsWith(\"external:\") ||\n    principalId.startsWith(\"external_viewer:\")\n  ) {\n    return \"external_viewer\";\n  }\n  return \"service\";\n}\n\nexport function normalizeDelegationChain(args: {\n  delegationChain?: readonly SessionDelegationHop[];\n  delegatedBy?: string;\n  delegatedByType?: SessionPrincipalType;\n  delegatedAt?: number;\n  reason?: string;\n}): SessionDelegationHop[] | undefined {\n  if (args.delegationChain && args.delegationChain.length > 0) {\n    return [...args.delegationChain];\n  }\n  if (!args.delegatedBy) {\n    return;\n  }\n  return [\n    {\n      principalId: args.delegatedBy,\n      principalType:\n        args.delegatedByType ?? inferSessionPrincipalType(args.delegatedBy),\n      delegatedAt: args.delegatedAt,\n      reason: args.reason,\n    },\n  ];\n}\n\nexport function lastDelegator(\n  delegationChain?: readonly SessionDelegationHop[]\n): string | undefined {\n  if (!delegationChain || delegationChain.length === 0) {\n    return;\n  }\n  return delegationChain[delegationChain.length - 1]?.principalId;\n}\n\n// =============================================================================\n// AUTH CONTEXT\n// (Formerly src/auth-context.contract.ts)\n// =============================================================================\n\nimport type { ConvexAdminClient } from \"./convex-admin.contract\";\n\nexport type McpTransportKind = \"stdio\" | \"hosted\";\n\nexport type LucernSdkClient = unknown;\n\n/**\n * Session authentication context — injected by withAuth() middleware.\n *\n * Built from TenantConfig at dispatch time. Agent sessions get\n * AGENT_IDENTITY + \"agent:internal\" role + unrestricted access.\n * User sessions get Clerk userId + resolved role + tool ACLs.\n */\nexport type AuthContext = {\n  sessionType: \"agent\" | \"user\";\n  userId: string; // AGENT_IDENTITY for agents, Clerk userId for users\n  tenantId: string;\n  role: string; // \"agent:internal\" | \"platform_admin\" | \"tenant_admin\" | \"editor\" | \"viewer\" | ...\n  allowedTopics: string[] | null; // null = unrestricted (agents, admins). Block 11D populates this.\n  // Layer 2a: Group-pack binding — resolved at boot from MC resolveUserPackAccess\n  groupIds: string[]; // Groups this user belongs to (empty for agents)\n  permittedPackKeys: string[]; // Packs accessible via group assignments (empty = no pack filtering)\n  sessionId: string; // S2-13K: MCP process session UUID for audit attribution\n  principalId?: string;\n  principalType?: SessionPrincipalType;\n  workspaceId?: string;\n  scopes?: string[];\n  authMode?: SessionAuthMode;\n  roles?: string[];\n  transportKind?: McpTransportKind;\n  lucernClient?: LucernSdkClient;\n  convex?: ConvexAdminClient;\n  setDefaultScopeContext?: (scopeId: string) => Promise<unknown>;\n  matchesWorkspaceReasoningScope?: (\n    node: unknown,\n    scope: unknown\n  ) => boolean;\n};\n"]}
+{"version":3,"sources":["../src/auth.contract.ts"],"names":[],"mappings":";AAgBO,IAAM,kBAAA,GAAqB;AAAA,EAChC,kBAAA;AAAA,EACA,mBAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACF;AAGO,IAAM,uBAAA,GAA0B;AAAA,EACrC,OAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF;AAGO,IAAM,0BAAA,GAA6B;AAAA,EACxC,QAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF;AA2CO,SAAS,0BACd,WAAA,EACsB;AACtB,EAAA,IAAI,qBAAA,CAAsB,IAAA,CAAK,WAAW,CAAA,EAAG;AAC3C,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IACE,YAAY,UAAA,CAAW,WAAW,KAClC,WAAA,CAAY,UAAA,CAAW,kBAAkB,CAAA,EACzC;AACA,IAAA,OAAO,iBAAA;AAAA,EACT;AACA,EAAA,OAAO,SAAA;AACT;AAEO,SAAS,yBAAyB,IAAA,EAMF;AACrC,EAAA,IAAI,IAAA,CAAK,eAAA,IAAmB,IAAA,CAAK,eAAA,CAAgB,SAAS,CAAA,EAAG;AAC3D,IAAA,OAAO,CAAC,GAAG,IAAA,CAAK,eAAe,CAAA;AAAA,EACjC;AACA,EAAA,IAAI,CAAC,KAAK,WAAA,EAAa;AACrB,IAAA;AAAA,EACF;AACA,EAAA,OAAO;AAAA,IACL;AAAA,MACE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,aAAA,EACE,IAAA,CAAK,eAAA,IAAmB,yBAAA,CAA0B,KAAK,WAAW,CAAA;AAAA,MACpE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,QAAQ,IAAA,CAAK;AAAA;AACf,GACF;AACF;AAEO,SAAS,cACd,eAAA,EACoB;AACpB,EAAA,IAAI,CAAC,eAAA,IAAmB,eAAA,CAAgB,MAAA,KAAW,CAAA,EAAG;AACpD,IAAA;AAAA,EACF;AACA,EAAA,OAAO,eAAA,CAAgB,eAAA,CAAgB,MAAA,GAAS,CAAC,CAAA,EAAG,WAAA;AACtD","file":"auth-context.contract.js","sourcesContent":["/**\n * @lucern/contracts — auth (canonical support contract)\n *\n * Consolidated flat support surface for Lucern authentication:\n *   - Session primitives (auth modes, principal types, lifecycle)\n *   - AuthContext shape + McpTransportKind + LucernSdkClient alias\n *\n * Consolidated from src/auth-session.contract.ts and src/auth-context.contract.ts\n * in EK-16 T1 PR 3a. Compat shims remain at both old paths until Lucern 1.0.0 (D12).\n */\n\n// =============================================================================\n// SESSION PRIMITIVES\n// (Formerly src/auth-session.contract.ts)\n// =============================================================================\n\nexport const SESSION_AUTH_MODES = [\n  \"interactive_user\",\n  \"service_principal\",\n  \"tenant_api_key\",\n  \"session_token\",\n] as const;\nexport type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];\n\nexport const SESSION_PRINCIPAL_TYPES = [\n  \"human\",\n  \"service\",\n  \"agent\",\n  \"group\",\n  \"external_viewer\",\n] as const;\nexport type SessionPrincipalType = (typeof SESSION_PRINCIPAL_TYPES)[number];\n\nexport const SESSION_LIFECYCLE_STATUSES = [\n  \"active\",\n  \"expired\",\n  \"revoked\",\n] as const;\nexport type SessionLifecycleStatus =\n  (typeof SESSION_LIFECYCLE_STATUSES)[number];\n\nexport type SessionDelegationHop = {\n  principalId: string;\n  principalType: SessionPrincipalType;\n  authMode?: SessionAuthMode;\n  sessionId?: string;\n  delegatedAt?: number;\n  reason?: string;\n};\n\nexport type SessionAuditOutcome =\n  | \"accepted\"\n  | \"rejected\"\n  | \"revoked\"\n  | \"expired\";\n\nexport type SessionAuditEnvelope = {\n  sessionId: string;\n  authMode: SessionAuthMode;\n  principalId: string;\n  principalType: SessionPrincipalType;\n  tenantId: string;\n  workspaceId?: string;\n  apiKeyId?: string;\n  scopes: readonly string[];\n  roles?: readonly string[];\n  delegationChain?: readonly SessionDelegationHop[];\n  sourceSessionId?: string;\n  expiresAt?: number;\n  request?: {\n    endpoint?: string;\n    method?: string;\n    correlationId?: string;\n  };\n  result?: {\n    outcome: SessionAuditOutcome;\n    reason?: string;\n  };\n};\n\nexport function inferSessionPrincipalType(\n  principalId: string\n): SessionPrincipalType {\n  if (/^user_[A-Za-z0-9]+$/.test(principalId)) {\n    return \"human\";\n  }\n  if (principalId.startsWith(\"agent:\")) {\n    return \"agent\";\n  }\n  if (principalId.startsWith(\"group:\")) {\n    return \"group\";\n  }\n  if (\n    principalId.startsWith(\"external:\") ||\n    principalId.startsWith(\"external_viewer:\")\n  ) {\n    return \"external_viewer\";\n  }\n  return \"service\";\n}\n\nexport function normalizeDelegationChain(args: {\n  delegationChain?: readonly SessionDelegationHop[];\n  delegatedBy?: string;\n  delegatedByType?: SessionPrincipalType;\n  delegatedAt?: number;\n  reason?: string;\n}): SessionDelegationHop[] | undefined {\n  if (args.delegationChain && args.delegationChain.length > 0) {\n    return [...args.delegationChain];\n  }\n  if (!args.delegatedBy) {\n    return;\n  }\n  return [\n    {\n      principalId: args.delegatedBy,\n      principalType:\n        args.delegatedByType ?? inferSessionPrincipalType(args.delegatedBy),\n      delegatedAt: args.delegatedAt,\n      reason: args.reason,\n    },\n  ];\n}\n\nexport function lastDelegator(\n  delegationChain?: readonly SessionDelegationHop[]\n): string | undefined {\n  if (!delegationChain || delegationChain.length === 0) {\n    return;\n  }\n  return delegationChain[delegationChain.length - 1]?.principalId;\n}\n\n// =============================================================================\n// AUTH CONTEXT\n// (Formerly src/auth-context.contract.ts)\n// =============================================================================\n\nimport type { ConvexAdminClient } from \"./convex-admin.contract\";\n\nexport type McpTransportKind = \"stdio\" | \"hosted\";\n\nexport type LucernSdkClient = unknown;\n\n/**\n * Session authentication context — injected by withAuth() middleware.\n *\n * Built from TenantConfig at dispatch time. Agent sessions get\n * AGENT_IDENTITY + \"agent:internal\" role + unrestricted access.\n * User sessions get Clerk userId + resolved role + tool ACLs.\n */\nexport type AuthContext = {\n  sessionType: \"agent\" | \"user\";\n  userId: string; // AGENT_IDENTITY for agents, Clerk userId for users\n  tenantId: string;\n  role: string; // \"agent:internal\" | \"platform_admin\" | \"tenant_admin\" | \"editor\" | \"viewer\" | ...\n  allowedTopics: string[] | null; // null = unrestricted (agents, admins). Block 11D populates this.\n  // Layer 2a: Group-pack binding — resolved at boot from MC resolveUserPackAccess\n  groupIds: string[]; // Groups this user belongs to (empty for agents)\n  permittedPackKeys: string[]; // Packs accessible via group assignments (empty = no pack filtering)\n  sessionId: string; // S2-13K: MCP process session UUID for audit attribution\n  principalId?: string;\n  principalType?: SessionPrincipalType;\n  workspaceId?: string;\n  scopes?: string[];\n  authMode?: SessionAuthMode;\n  roles?: string[];\n  transportKind?: McpTransportKind;\n  lucernClient?: LucernSdkClient;\n  convex?: ConvexAdminClient;\n  setDefaultScopeContext?: (scopeId: string) => Promise<unknown>;\n  matchesWorkspaceReasoningScope?: (\n    node: unknown,\n    scope: unknown\n  ) => boolean;\n};\n"]}

package/dist/auth-session.contract.js

@@ -18,7 +18,7 @@ var SESSION_LIFECYCLE_STATUSES = [
   "revoked"
 ];
 function inferSessionPrincipalType(principalId) {
-  if (principalId.startsWith("user:")) {
+  if (/^user_[A-Za-z0-9]+$/.test(principalId)) {
     return "human";
   }
   if (principalId.startsWith("agent:")) {

package/dist/auth-session.contract.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/auth.contract.ts"],"names":[],"mappings":";AAgBO,IAAM,kBAAA,GAAqB;AAAA,EAChC,kBAAA;AAAA,EACA,mBAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACF;AAGO,IAAM,uBAAA,GAA0B;AAAA,EACrC,OAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF;AAGO,IAAM,0BAAA,GAA6B;AAAA,EACxC,QAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF;AA2CO,SAAS,0BACd,WAAA,EACsB;AACtB,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,OAAO,CAAA,EAAG;AACnC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IACE,YAAY,UAAA,CAAW,WAAW,KAClC,WAAA,CAAY,UAAA,CAAW,kBAAkB,CAAA,EACzC;AACA,IAAA,OAAO,iBAAA;AAAA,EACT;AACA,EAAA,OAAO,SAAA;AACT;AAEO,SAAS,yBAAyB,IAAA,EAMF;AACrC,EAAA,IAAI,IAAA,CAAK,eAAA,IAAmB,IAAA,CAAK,eAAA,CAAgB,SAAS,CAAA,EAAG;AAC3D,IAAA,OAAO,CAAC,GAAG,IAAA,CAAK,eAAe,CAAA;AAAA,EACjC;AACA,EAAA,IAAI,CAAC,KAAK,WAAA,EAAa;AACrB,IAAA;AAAA,EACF;AACA,EAAA,OAAO;AAAA,IACL;AAAA,MACE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,aAAA,EACE,IAAA,CAAK,eAAA,IAAmB,yBAAA,CAA0B,KAAK,WAAW,CAAA;AAAA,MACpE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,QAAQ,IAAA,CAAK;AAAA;AACf,GACF;AACF;AAEO,SAAS,cACd,eAAA,EACoB;AACpB,EAAA,IAAI,CAAC,eAAA,IAAmB,eAAA,CAAgB,MAAA,KAAW,CAAA,EAAG;AACpD,IAAA;AAAA,EACF;AACA,EAAA,OAAO,eAAA,CAAgB,eAAA,CAAgB,MAAA,GAAS,CAAC,CAAA,EAAG,WAAA;AACtD","file":"auth-session.contract.js","sourcesContent":["/**\n * @lucern/contracts — auth (canonical support contract)\n *\n * Consolidated flat support surface for Lucern authentication:\n *   - Session primitives (auth modes, principal types, lifecycle)\n *   - AuthContext shape + McpTransportKind + LucernSdkClient alias\n *\n * Consolidated from src/auth-session.contract.ts and src/auth-context.contract.ts\n * in EK-16 T1 PR 3a. Compat shims remain at both old paths until Lucern 1.0.0 (D12).\n */\n\n// =============================================================================\n// SESSION PRIMITIVES\n// (Formerly src/auth-session.contract.ts)\n// =============================================================================\n\nexport const SESSION_AUTH_MODES = [\n  \"interactive_user\",\n  \"service_principal\",\n  \"tenant_api_key\",\n  \"session_token\",\n] as const;\nexport type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];\n\nexport const SESSION_PRINCIPAL_TYPES = [\n  \"human\",\n  \"service\",\n  \"agent\",\n  \"group\",\n  \"external_viewer\",\n] as const;\nexport type SessionPrincipalType = (typeof SESSION_PRINCIPAL_TYPES)[number];\n\nexport const SESSION_LIFECYCLE_STATUSES = [\n  \"active\",\n  \"expired\",\n  \"revoked\",\n] as const;\nexport type SessionLifecycleStatus =\n  (typeof SESSION_LIFECYCLE_STATUSES)[number];\n\nexport type SessionDelegationHop = {\n  principalId: string;\n  principalType: SessionPrincipalType;\n  authMode?: SessionAuthMode;\n  sessionId?: string;\n  delegatedAt?: number;\n  reason?: string;\n};\n\nexport type SessionAuditOutcome =\n  | \"accepted\"\n  | \"rejected\"\n  | \"revoked\"\n  | \"expired\";\n\nexport type SessionAuditEnvelope = {\n  sessionId: string;\n  authMode: SessionAuthMode;\n  principalId: string;\n  principalType: SessionPrincipalType;\n  tenantId: string;\n  workspaceId?: string;\n  apiKeyId?: string;\n  scopes: readonly string[];\n  roles?: readonly string[];\n  delegationChain?: readonly SessionDelegationHop[];\n  sourceSessionId?: string;\n  expiresAt?: number;\n  request?: {\n    endpoint?: string;\n    method?: string;\n    correlationId?: string;\n  };\n  result?: {\n    outcome: SessionAuditOutcome;\n    reason?: string;\n  };\n};\n\nexport function inferSessionPrincipalType(\n  principalId: string\n): SessionPrincipalType {\n  if (principalId.startsWith(\"user:\")) {\n    return \"human\";\n  }\n  if (principalId.startsWith(\"agent:\")) {\n    return \"agent\";\n  }\n  if (principalId.startsWith(\"group:\")) {\n    return \"group\";\n  }\n  if (\n    principalId.startsWith(\"external:\") ||\n    principalId.startsWith(\"external_viewer:\")\n  ) {\n    return \"external_viewer\";\n  }\n  return \"service\";\n}\n\nexport function normalizeDelegationChain(args: {\n  delegationChain?: readonly SessionDelegationHop[];\n  delegatedBy?: string;\n  delegatedByType?: SessionPrincipalType;\n  delegatedAt?: number;\n  reason?: string;\n}): SessionDelegationHop[] | undefined {\n  if (args.delegationChain && args.delegationChain.length > 0) {\n    return [...args.delegationChain];\n  }\n  if (!args.delegatedBy) {\n    return;\n  }\n  return [\n    {\n      principalId: args.delegatedBy,\n      principalType:\n        args.delegatedByType ?? inferSessionPrincipalType(args.delegatedBy),\n      delegatedAt: args.delegatedAt,\n      reason: args.reason,\n    },\n  ];\n}\n\nexport function lastDelegator(\n  delegationChain?: readonly SessionDelegationHop[]\n): string | undefined {\n  if (!delegationChain || delegationChain.length === 0) {\n    return;\n  }\n  return delegationChain[delegationChain.length - 1]?.principalId;\n}\n\n// =============================================================================\n// AUTH CONTEXT\n// (Formerly src/auth-context.contract.ts)\n// =============================================================================\n\nimport type { ConvexAdminClient } from \"./convex-admin.contract\";\n\nexport type McpTransportKind = \"stdio\" | \"hosted\";\n\nexport type LucernSdkClient = unknown;\n\n/**\n * Session authentication context — injected by withAuth() middleware.\n *\n * Built from TenantConfig at dispatch time. Agent sessions get\n * AGENT_IDENTITY + \"agent:internal\" role + unrestricted access.\n * User sessions get Clerk userId + resolved role + tool ACLs.\n */\nexport type AuthContext = {\n  sessionType: \"agent\" | \"user\";\n  userId: string; // AGENT_IDENTITY for agents, Clerk userId for users\n  tenantId: string;\n  role: string; // \"agent:internal\" | \"platform_admin\" | \"tenant_admin\" | \"editor\" | \"viewer\" | ...\n  allowedTopics: string[] | null; // null = unrestricted (agents, admins). Block 11D populates this.\n  // Layer 2a: Group-pack binding — resolved at boot from MC resolveUserPackAccess\n  groupIds: string[]; // Groups this user belongs to (empty for agents)\n  permittedPackKeys: string[]; // Packs accessible via group assignments (empty = no pack filtering)\n  sessionId: string; // S2-13K: MCP process session UUID for audit attribution\n  principalId?: string;\n  principalType?: SessionPrincipalType;\n  workspaceId?: string;\n  scopes?: string[];\n  authMode?: SessionAuthMode;\n  roles?: string[];\n  transportKind?: McpTransportKind;\n  lucernClient?: LucernSdkClient;\n  convex?: ConvexAdminClient;\n  setDefaultScopeContext?: (scopeId: string) => Promise<unknown>;\n  matchesWorkspaceReasoningScope?: (\n    node: unknown,\n    scope: unknown\n  ) => boolean;\n};\n"]}
+{"version":3,"sources":["../src/auth.contract.ts"],"names":[],"mappings":";AAgBO,IAAM,kBAAA,GAAqB;AAAA,EAChC,kBAAA;AAAA,EACA,mBAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACF;AAGO,IAAM,uBAAA,GAA0B;AAAA,EACrC,OAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF;AAGO,IAAM,0BAAA,GAA6B;AAAA,EACxC,QAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF;AA2CO,SAAS,0BACd,WAAA,EACsB;AACtB,EAAA,IAAI,qBAAA,CAAsB,IAAA,CAAK,WAAW,CAAA,EAAG;AAC3C,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IACE,YAAY,UAAA,CAAW,WAAW,KAClC,WAAA,CAAY,UAAA,CAAW,kBAAkB,CAAA,EACzC;AACA,IAAA,OAAO,iBAAA;AAAA,EACT;AACA,EAAA,OAAO,SAAA;AACT;AAEO,SAAS,yBAAyB,IAAA,EAMF;AACrC,EAAA,IAAI,IAAA,CAAK,eAAA,IAAmB,IAAA,CAAK,eAAA,CAAgB,SAAS,CAAA,EAAG;AAC3D,IAAA,OAAO,CAAC,GAAG,IAAA,CAAK,eAAe,CAAA;AAAA,EACjC;AACA,EAAA,IAAI,CAAC,KAAK,WAAA,EAAa;AACrB,IAAA;AAAA,EACF;AACA,EAAA,OAAO;AAAA,IACL;AAAA,MACE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,aAAA,EACE,IAAA,CAAK,eAAA,IAAmB,yBAAA,CAA0B,KAAK,WAAW,CAAA;AAAA,MACpE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,QAAQ,IAAA,CAAK;AAAA;AACf,GACF;AACF;AAEO,SAAS,cACd,eAAA,EACoB;AACpB,EAAA,IAAI,CAAC,eAAA,IAAmB,eAAA,CAAgB,MAAA,KAAW,CAAA,EAAG;AACpD,IAAA;AAAA,EACF;AACA,EAAA,OAAO,eAAA,CAAgB,eAAA,CAAgB,MAAA,GAAS,CAAC,CAAA,EAAG,WAAA;AACtD","file":"auth-session.contract.js","sourcesContent":["/**\n * @lucern/contracts — auth (canonical support contract)\n *\n * Consolidated flat support surface for Lucern authentication:\n *   - Session primitives (auth modes, principal types, lifecycle)\n *   - AuthContext shape + McpTransportKind + LucernSdkClient alias\n *\n * Consolidated from src/auth-session.contract.ts and src/auth-context.contract.ts\n * in EK-16 T1 PR 3a. Compat shims remain at both old paths until Lucern 1.0.0 (D12).\n */\n\n// =============================================================================\n// SESSION PRIMITIVES\n// (Formerly src/auth-session.contract.ts)\n// =============================================================================\n\nexport const SESSION_AUTH_MODES = [\n  \"interactive_user\",\n  \"service_principal\",\n  \"tenant_api_key\",\n  \"session_token\",\n] as const;\nexport type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];\n\nexport const SESSION_PRINCIPAL_TYPES = [\n  \"human\",\n  \"service\",\n  \"agent\",\n  \"group\",\n  \"external_viewer\",\n] as const;\nexport type SessionPrincipalType = (typeof SESSION_PRINCIPAL_TYPES)[number];\n\nexport const SESSION_LIFECYCLE_STATUSES = [\n  \"active\",\n  \"expired\",\n  \"revoked\",\n] as const;\nexport type SessionLifecycleStatus =\n  (typeof SESSION_LIFECYCLE_STATUSES)[number];\n\nexport type SessionDelegationHop = {\n  principalId: string;\n  principalType: SessionPrincipalType;\n  authMode?: SessionAuthMode;\n  sessionId?: string;\n  delegatedAt?: number;\n  reason?: string;\n};\n\nexport type SessionAuditOutcome =\n  | \"accepted\"\n  | \"rejected\"\n  | \"revoked\"\n  | \"expired\";\n\nexport type SessionAuditEnvelope = {\n  sessionId: string;\n  authMode: SessionAuthMode;\n  principalId: string;\n  principalType: SessionPrincipalType;\n  tenantId: string;\n  workspaceId?: string;\n  apiKeyId?: string;\n  scopes: readonly string[];\n  roles?: readonly string[];\n  delegationChain?: readonly SessionDelegationHop[];\n  sourceSessionId?: string;\n  expiresAt?: number;\n  request?: {\n    endpoint?: string;\n    method?: string;\n    correlationId?: string;\n  };\n  result?: {\n    outcome: SessionAuditOutcome;\n    reason?: string;\n  };\n};\n\nexport function inferSessionPrincipalType(\n  principalId: string\n): SessionPrincipalType {\n  if (/^user_[A-Za-z0-9]+$/.test(principalId)) {\n    return \"human\";\n  }\n  if (principalId.startsWith(\"agent:\")) {\n    return \"agent\";\n  }\n  if (principalId.startsWith(\"group:\")) {\n    return \"group\";\n  }\n  if (\n    principalId.startsWith(\"external:\") ||\n    principalId.startsWith(\"external_viewer:\")\n  ) {\n    return \"external_viewer\";\n  }\n  return \"service\";\n}\n\nexport function normalizeDelegationChain(args: {\n  delegationChain?: readonly SessionDelegationHop[];\n  delegatedBy?: string;\n  delegatedByType?: SessionPrincipalType;\n  delegatedAt?: number;\n  reason?: string;\n}): SessionDelegationHop[] | undefined {\n  if (args.delegationChain && args.delegationChain.length > 0) {\n    return [...args.delegationChain];\n  }\n  if (!args.delegatedBy) {\n    return;\n  }\n  return [\n    {\n      principalId: args.delegatedBy,\n      principalType:\n        args.delegatedByType ?? inferSessionPrincipalType(args.delegatedBy),\n      delegatedAt: args.delegatedAt,\n      reason: args.reason,\n    },\n  ];\n}\n\nexport function lastDelegator(\n  delegationChain?: readonly SessionDelegationHop[]\n): string | undefined {\n  if (!delegationChain || delegationChain.length === 0) {\n    return;\n  }\n  return delegationChain[delegationChain.length - 1]?.principalId;\n}\n\n// =============================================================================\n// AUTH CONTEXT\n// (Formerly src/auth-context.contract.ts)\n// =============================================================================\n\nimport type { ConvexAdminClient } from \"./convex-admin.contract\";\n\nexport type McpTransportKind = \"stdio\" | \"hosted\";\n\nexport type LucernSdkClient = unknown;\n\n/**\n * Session authentication context — injected by withAuth() middleware.\n *\n * Built from TenantConfig at dispatch time. Agent sessions get\n * AGENT_IDENTITY + \"agent:internal\" role + unrestricted access.\n * User sessions get Clerk userId + resolved role + tool ACLs.\n */\nexport type AuthContext = {\n  sessionType: \"agent\" | \"user\";\n  userId: string; // AGENT_IDENTITY for agents, Clerk userId for users\n  tenantId: string;\n  role: string; // \"agent:internal\" | \"platform_admin\" | \"tenant_admin\" | \"editor\" | \"viewer\" | ...\n  allowedTopics: string[] | null; // null = unrestricted (agents, admins). Block 11D populates this.\n  // Layer 2a: Group-pack binding — resolved at boot from MC resolveUserPackAccess\n  groupIds: string[]; // Groups this user belongs to (empty for agents)\n  permittedPackKeys: string[]; // Packs accessible via group assignments (empty = no pack filtering)\n  sessionId: string; // S2-13K: MCP process session UUID for audit attribution\n  principalId?: string;\n  principalType?: SessionPrincipalType;\n  workspaceId?: string;\n  scopes?: string[];\n  authMode?: SessionAuthMode;\n  roles?: string[];\n  transportKind?: McpTransportKind;\n  lucernClient?: LucernSdkClient;\n  convex?: ConvexAdminClient;\n  setDefaultScopeContext?: (scopeId: string) => Promise<unknown>;\n  matchesWorkspaceReasoningScope?: (\n    node: unknown,\n    scope: unknown\n  ) => boolean;\n};\n"]}

package/dist/auth.contract.js

@@ -18,7 +18,7 @@ var SESSION_LIFECYCLE_STATUSES = [
   "revoked"
 ];
 function inferSessionPrincipalType(principalId) {
-  if (principalId.startsWith("user:")) {
+  if (/^user_[A-Za-z0-9]+$/.test(principalId)) {
     return "human";
   }
   if (principalId.startsWith("agent:")) {

package/dist/auth.contract.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/auth.contract.ts"],"names":[],"mappings":";AAgBO,IAAM,kBAAA,GAAqB;AAAA,EAChC,kBAAA;AAAA,EACA,mBAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACF;AAGO,IAAM,uBAAA,GAA0B;AAAA,EACrC,OAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF;AAGO,IAAM,0BAAA,GAA6B;AAAA,EACxC,QAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF;AA2CO,SAAS,0BACd,WAAA,EACsB;AACtB,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,OAAO,CAAA,EAAG;AACnC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IACE,YAAY,UAAA,CAAW,WAAW,KAClC,WAAA,CAAY,UAAA,CAAW,kBAAkB,CAAA,EACzC;AACA,IAAA,OAAO,iBAAA;AAAA,EACT;AACA,EAAA,OAAO,SAAA;AACT;AAEO,SAAS,yBAAyB,IAAA,EAMF;AACrC,EAAA,IAAI,IAAA,CAAK,eAAA,IAAmB,IAAA,CAAK,eAAA,CAAgB,SAAS,CAAA,EAAG;AAC3D,IAAA,OAAO,CAAC,GAAG,IAAA,CAAK,eAAe,CAAA;AAAA,EACjC;AACA,EAAA,IAAI,CAAC,KAAK,WAAA,EAAa;AACrB,IAAA;AAAA,EACF;AACA,EAAA,OAAO;AAAA,IACL;AAAA,MACE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,aAAA,EACE,IAAA,CAAK,eAAA,IAAmB,yBAAA,CAA0B,KAAK,WAAW,CAAA;AAAA,MACpE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,QAAQ,IAAA,CAAK;AAAA;AACf,GACF;AACF;AAEO,SAAS,cACd,eAAA,EACoB;AACpB,EAAA,IAAI,CAAC,eAAA,IAAmB,eAAA,CAAgB,MAAA,KAAW,CAAA,EAAG;AACpD,IAAA;AAAA,EACF;AACA,EAAA,OAAO,eAAA,CAAgB,eAAA,CAAgB,MAAA,GAAS,CAAC,CAAA,EAAG,WAAA;AACtD","file":"auth.contract.js","sourcesContent":["/**\n * @lucern/contracts — auth (canonical support contract)\n *\n * Consolidated flat support surface for Lucern authentication:\n *   - Session primitives (auth modes, principal types, lifecycle)\n *   - AuthContext shape + McpTransportKind + LucernSdkClient alias\n *\n * Consolidated from src/auth-session.contract.ts and src/auth-context.contract.ts\n * in EK-16 T1 PR 3a. Compat shims remain at both old paths until Lucern 1.0.0 (D12).\n */\n\n// =============================================================================\n// SESSION PRIMITIVES\n// (Formerly src/auth-session.contract.ts)\n// =============================================================================\n\nexport const SESSION_AUTH_MODES = [\n  \"interactive_user\",\n  \"service_principal\",\n  \"tenant_api_key\",\n  \"session_token\",\n] as const;\nexport type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];\n\nexport const SESSION_PRINCIPAL_TYPES = [\n  \"human\",\n  \"service\",\n  \"agent\",\n  \"group\",\n  \"external_viewer\",\n] as const;\nexport type SessionPrincipalType = (typeof SESSION_PRINCIPAL_TYPES)[number];\n\nexport const SESSION_LIFECYCLE_STATUSES = [\n  \"active\",\n  \"expired\",\n  \"revoked\",\n] as const;\nexport type SessionLifecycleStatus =\n  (typeof SESSION_LIFECYCLE_STATUSES)[number];\n\nexport type SessionDelegationHop = {\n  principalId: string;\n  principalType: SessionPrincipalType;\n  authMode?: SessionAuthMode;\n  sessionId?: string;\n  delegatedAt?: number;\n  reason?: string;\n};\n\nexport type SessionAuditOutcome =\n  | \"accepted\"\n  | \"rejected\"\n  | \"revoked\"\n  | \"expired\";\n\nexport type SessionAuditEnvelope = {\n  sessionId: string;\n  authMode: SessionAuthMode;\n  principalId: string;\n  principalType: SessionPrincipalType;\n  tenantId: string;\n  workspaceId?: string;\n  apiKeyId?: string;\n  scopes: readonly string[];\n  roles?: readonly string[];\n  delegationChain?: readonly SessionDelegationHop[];\n  sourceSessionId?: string;\n  expiresAt?: number;\n  request?: {\n    endpoint?: string;\n    method?: string;\n    correlationId?: string;\n  };\n  result?: {\n    outcome: SessionAuditOutcome;\n    reason?: string;\n  };\n};\n\nexport function inferSessionPrincipalType(\n  principalId: string\n): SessionPrincipalType {\n  if (principalId.startsWith(\"user:\")) {\n    return \"human\";\n  }\n  if (principalId.startsWith(\"agent:\")) {\n    return \"agent\";\n  }\n  if (principalId.startsWith(\"group:\")) {\n    return \"group\";\n  }\n  if (\n    principalId.startsWith(\"external:\") ||\n    principalId.startsWith(\"external_viewer:\")\n  ) {\n    return \"external_viewer\";\n  }\n  return \"service\";\n}\n\nexport function normalizeDelegationChain(args: {\n  delegationChain?: readonly SessionDelegationHop[];\n  delegatedBy?: string;\n  delegatedByType?: SessionPrincipalType;\n  delegatedAt?: number;\n  reason?: string;\n}): SessionDelegationHop[] | undefined {\n  if (args.delegationChain && args.delegationChain.length > 0) {\n    return [...args.delegationChain];\n  }\n  if (!args.delegatedBy) {\n    return;\n  }\n  return [\n    {\n      principalId: args.delegatedBy,\n      principalType:\n        args.delegatedByType ?? inferSessionPrincipalType(args.delegatedBy),\n      delegatedAt: args.delegatedAt,\n      reason: args.reason,\n    },\n  ];\n}\n\nexport function lastDelegator(\n  delegationChain?: readonly SessionDelegationHop[]\n): string | undefined {\n  if (!delegationChain || delegationChain.length === 0) {\n    return;\n  }\n  return delegationChain[delegationChain.length - 1]?.principalId;\n}\n\n// =============================================================================\n// AUTH CONTEXT\n// (Formerly src/auth-context.contract.ts)\n// =============================================================================\n\nimport type { ConvexAdminClient } from \"./convex-admin.contract\";\n\nexport type McpTransportKind = \"stdio\" | \"hosted\";\n\nexport type LucernSdkClient = unknown;\n\n/**\n * Session authentication context — injected by withAuth() middleware.\n *\n * Built from TenantConfig at dispatch time. Agent sessions get\n * AGENT_IDENTITY + \"agent:internal\" role + unrestricted access.\n * User sessions get Clerk userId + resolved role + tool ACLs.\n */\nexport type AuthContext = {\n  sessionType: \"agent\" | \"user\";\n  userId: string; // AGENT_IDENTITY for agents, Clerk userId for users\n  tenantId: string;\n  role: string; // \"agent:internal\" | \"platform_admin\" | \"tenant_admin\" | \"editor\" | \"viewer\" | ...\n  allowedTopics: string[] | null; // null = unrestricted (agents, admins). Block 11D populates this.\n  // Layer 2a: Group-pack binding — resolved at boot from MC resolveUserPackAccess\n  groupIds: string[]; // Groups this user belongs to (empty for agents)\n  permittedPackKeys: string[]; // Packs accessible via group assignments (empty = no pack filtering)\n  sessionId: string; // S2-13K: MCP process session UUID for audit attribution\n  principalId?: string;\n  principalType?: SessionPrincipalType;\n  workspaceId?: string;\n  scopes?: string[];\n  authMode?: SessionAuthMode;\n  roles?: string[];\n  transportKind?: McpTransportKind;\n  lucernClient?: LucernSdkClient;\n  convex?: ConvexAdminClient;\n  setDefaultScopeContext?: (scopeId: string) => Promise<unknown>;\n  matchesWorkspaceReasoningScope?: (\n    node: unknown,\n    scope: unknown\n  ) => boolean;\n};\n"]}
+{"version":3,"sources":["../src/auth.contract.ts"],"names":[],"mappings":";AAgBO,IAAM,kBAAA,GAAqB;AAAA,EAChC,kBAAA;AAAA,EACA,mBAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACF;AAGO,IAAM,uBAAA,GAA0B;AAAA,EACrC,OAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF;AAGO,IAAM,0BAAA,GAA6B;AAAA,EACxC,QAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF;AA2CO,SAAS,0BACd,WAAA,EACsB;AACtB,EAAA,IAAI,qBAAA,CAAsB,IAAA,CAAK,WAAW,CAAA,EAAG;AAC3C,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,WAAA,CAAY,UAAA,CAAW,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IACE,YAAY,UAAA,CAAW,WAAW,KAClC,WAAA,CAAY,UAAA,CAAW,kBAAkB,CAAA,EACzC;AACA,IAAA,OAAO,iBAAA;AAAA,EACT;AACA,EAAA,OAAO,SAAA;AACT;AAEO,SAAS,yBAAyB,IAAA,EAMF;AACrC,EAAA,IAAI,IAAA,CAAK,eAAA,IAAmB,IAAA,CAAK,eAAA,CAAgB,SAAS,CAAA,EAAG;AAC3D,IAAA,OAAO,CAAC,GAAG,IAAA,CAAK,eAAe,CAAA;AAAA,EACjC;AACA,EAAA,IAAI,CAAC,KAAK,WAAA,EAAa;AACrB,IAAA;AAAA,EACF;AACA,EAAA,OAAO;AAAA,IACL;AAAA,MACE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,aAAA,EACE,IAAA,CAAK,eAAA,IAAmB,yBAAA,CAA0B,KAAK,WAAW,CAAA;AAAA,MACpE,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,QAAQ,IAAA,CAAK;AAAA;AACf,GACF;AACF;AAEO,SAAS,cACd,eAAA,EACoB;AACpB,EAAA,IAAI,CAAC,eAAA,IAAmB,eAAA,CAAgB,MAAA,KAAW,CAAA,EAAG;AACpD,IAAA;AAAA,EACF;AACA,EAAA,OAAO,eAAA,CAAgB,eAAA,CAAgB,MAAA,GAAS,CAAC,CAAA,EAAG,WAAA;AACtD","file":"auth.contract.js","sourcesContent":["/**\n * @lucern/contracts — auth (canonical support contract)\n *\n * Consolidated flat support surface for Lucern authentication:\n *   - Session primitives (auth modes, principal types, lifecycle)\n *   - AuthContext shape + McpTransportKind + LucernSdkClient alias\n *\n * Consolidated from src/auth-session.contract.ts and src/auth-context.contract.ts\n * in EK-16 T1 PR 3a. Compat shims remain at both old paths until Lucern 1.0.0 (D12).\n */\n\n// =============================================================================\n// SESSION PRIMITIVES\n// (Formerly src/auth-session.contract.ts)\n// =============================================================================\n\nexport const SESSION_AUTH_MODES = [\n  \"interactive_user\",\n  \"service_principal\",\n  \"tenant_api_key\",\n  \"session_token\",\n] as const;\nexport type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];\n\nexport const SESSION_PRINCIPAL_TYPES = [\n  \"human\",\n  \"service\",\n  \"agent\",\n  \"group\",\n  \"external_viewer\",\n] as const;\nexport type SessionPrincipalType = (typeof SESSION_PRINCIPAL_TYPES)[number];\n\nexport const SESSION_LIFECYCLE_STATUSES = [\n  \"active\",\n  \"expired\",\n  \"revoked\",\n] as const;\nexport type SessionLifecycleStatus =\n  (typeof SESSION_LIFECYCLE_STATUSES)[number];\n\nexport type SessionDelegationHop = {\n  principalId: string;\n  principalType: SessionPrincipalType;\n  authMode?: SessionAuthMode;\n  sessionId?: string;\n  delegatedAt?: number;\n  reason?: string;\n};\n\nexport type SessionAuditOutcome =\n  | \"accepted\"\n  | \"rejected\"\n  | \"revoked\"\n  | \"expired\";\n\nexport type SessionAuditEnvelope = {\n  sessionId: string;\n  authMode: SessionAuthMode;\n  principalId: string;\n  principalType: SessionPrincipalType;\n  tenantId: string;\n  workspaceId?: string;\n  apiKeyId?: string;\n  scopes: readonly string[];\n  roles?: readonly string[];\n  delegationChain?: readonly SessionDelegationHop[];\n  sourceSessionId?: string;\n  expiresAt?: number;\n  request?: {\n    endpoint?: string;\n    method?: string;\n    correlationId?: string;\n  };\n  result?: {\n    outcome: SessionAuditOutcome;\n    reason?: string;\n  };\n};\n\nexport function inferSessionPrincipalType(\n  principalId: string\n): SessionPrincipalType {\n  if (/^user_[A-Za-z0-9]+$/.test(principalId)) {\n    return \"human\";\n  }\n  if (principalId.startsWith(\"agent:\")) {\n    return \"agent\";\n  }\n  if (principalId.startsWith(\"group:\")) {\n    return \"group\";\n  }\n  if (\n    principalId.startsWith(\"external:\") ||\n    principalId.startsWith(\"external_viewer:\")\n  ) {\n    return \"external_viewer\";\n  }\n  return \"service\";\n}\n\nexport function normalizeDelegationChain(args: {\n  delegationChain?: readonly SessionDelegationHop[];\n  delegatedBy?: string;\n  delegatedByType?: SessionPrincipalType;\n  delegatedAt?: number;\n  reason?: string;\n}): SessionDelegationHop[] | undefined {\n  if (args.delegationChain && args.delegationChain.length > 0) {\n    return [...args.delegationChain];\n  }\n  if (!args.delegatedBy) {\n    return;\n  }\n  return [\n    {\n      principalId: args.delegatedBy,\n      principalType:\n        args.delegatedByType ?? inferSessionPrincipalType(args.delegatedBy),\n      delegatedAt: args.delegatedAt,\n      reason: args.reason,\n    },\n  ];\n}\n\nexport function lastDelegator(\n  delegationChain?: readonly SessionDelegationHop[]\n): string | undefined {\n  if (!delegationChain || delegationChain.length === 0) {\n    return;\n  }\n  return delegationChain[delegationChain.length - 1]?.principalId;\n}\n\n// =============================================================================\n// AUTH CONTEXT\n// (Formerly src/auth-context.contract.ts)\n// =============================================================================\n\nimport type { ConvexAdminClient } from \"./convex-admin.contract\";\n\nexport type McpTransportKind = \"stdio\" | \"hosted\";\n\nexport type LucernSdkClient = unknown;\n\n/**\n * Session authentication context — injected by withAuth() middleware.\n *\n * Built from TenantConfig at dispatch time. Agent sessions get\n * AGENT_IDENTITY + \"agent:internal\" role + unrestricted access.\n * User sessions get Clerk userId + resolved role + tool ACLs.\n */\nexport type AuthContext = {\n  sessionType: \"agent\" | \"user\";\n  userId: string; // AGENT_IDENTITY for agents, Clerk userId for users\n  tenantId: string;\n  role: string; // \"agent:internal\" | \"platform_admin\" | \"tenant_admin\" | \"editor\" | \"viewer\" | ...\n  allowedTopics: string[] | null; // null = unrestricted (agents, admins). Block 11D populates this.\n  // Layer 2a: Group-pack binding — resolved at boot from MC resolveUserPackAccess\n  groupIds: string[]; // Groups this user belongs to (empty for agents)\n  permittedPackKeys: string[]; // Packs accessible via group assignments (empty = no pack filtering)\n  sessionId: string; // S2-13K: MCP process session UUID for audit attribution\n  principalId?: string;\n  principalType?: SessionPrincipalType;\n  workspaceId?: string;\n  scopes?: string[];\n  authMode?: SessionAuthMode;\n  roles?: string[];\n  transportKind?: McpTransportKind;\n  lucernClient?: LucernSdkClient;\n  convex?: ConvexAdminClient;\n  setDefaultScopeContext?: (scopeId: string) => Promise<unknown>;\n  matchesWorkspaceReasoningScope?: (\n    node: unknown,\n    scope: unknown\n  ) => boolean;\n};\n"]}

package/dist/function-registry/beliefs.js

@@ -2328,7 +2328,7 @@ var IDENTITY_WHOAMI = {
   response: {
     description: "Canonical identity summary for the current session",
     fields: {
-      principalId: "string \u2014 canonical federated principal identifier",
+      principalId: "string \u2014 canonical principal identifier; for humans this is the Clerk user_... ID",
       principalType: "string \u2014 human, service, agent, group, or external_viewer",
       tenantId: "string | undefined \u2014 resolved tenant scope",
       workspaceId: "string | undefined \u2014 resolved workspace scope",
@@ -2342,7 +2342,7 @@ var IDENTITY_WHOAMI = {
 };
 var RESOLVE_INTERACTIVE_PRINCIPAL = {
   name: "resolve_interactive_principal",
-  description: "Read the Permit-backed Lucern principal context for an authenticated Clerk user. Like `git config --get user.email` plus the repository ACL \u2014 resolves the identity alias into the canonical authorization subject.",
+  description: "Read the Permit-backed Lucern principal context for an authenticated Clerk user. Like `git config --get user.email` plus the repository ACL \u2014 resolves the Clerk subject into tenant/workspace authorization context.",
   parameters: {
     clerkId: {
       type: "string",
@@ -2365,7 +2365,7 @@ var RESOLVE_INTERACTIVE_PRINCIPAL = {
   response: {
     description: "Permit-backed Lucern principal context for tenant SDK bootstrap",
     fields: {
-      principalId: "string \u2014 canonical Lucern principal identifier",
+      principalId: "string \u2014 canonical Clerk user_... ID for human sessions",
       principalType: "string \u2014 human, service, agent, group, or external_viewer",
       clerkId: "string \u2014 authenticated Clerk subject alias",
       tenantId: "string \u2014 resolved tenant scope",
@@ -3193,7 +3193,7 @@ var MANAGE_WRITE_POLICY = {
     },
     role: {
       type: "string",
-      description: "Role to set policy for (required for 'set'). E.g. 'agent:internal', 'user:analyst'."
+      description: "Role to set policy for (required for 'set'). E.g. 'agent:internal' or a Permit role key such as 'workspace_admin'."
     },
     permission: {
       type: "string",