@byok-sdk/core 0.4.2 → 0.5.0

package/README.md

@@ -8,4 +8,11 @@ This package is runtime-neutral: it has no Node built-in or protocol dependency.
 import { tenantId, InMemoryCoreStores } from '@byok-sdk/core';
 ```
 
+For connector setup, `authenticateDeviceAssertion()` verifies exact trusted
+issuer/product/audience bindings, derives the principal from the current device
+row, and consumes the JTI through an injected `DeviceAssertionReplayAuthority`.
+`InMemoryDeviceAssertionReplayAuthority` is the reference implementation; a
+hosted production composition must inject durable atomic storage. The assertion
+authorizes one exchange only and is not a connector session or refresh token.
+
 MIT licensed. Node.js 22.22.0 or newer.

package/dist/device-assertion.d.ts

@@ -44,6 +44,8 @@
  */
 import { z } from 'zod';
 import { type JsonObject } from './attestation';
+import type { DevicePrincipal } from './principals';
+import { type TenantId } from './tenant';
 /** Envelope schema id, self-consistent with the domain prefix below. */
 export declare const DEVICE_ASSERTION_SCHEMA_ID = "byok-device-assertion-v1";
 /**
@@ -222,3 +224,58 @@ export interface DeviceAssertionVerifyDeps {
  * verifier's job.
  */
 export declare function verifyDeviceAssertion(input: unknown, deps: DeviceAssertionVerifyDeps): Promise<DeviceAssertionClaims | undefined>;
+/** The verifier's complete current row. Claims remain lookup keys, never authority. */
+export interface DeviceAssertionAuthorityRow extends DeviceAssertionDeviceRow {
+    readonly tenantId: TenantId;
+    readonly productId: string;
+    readonly deviceId: string;
+}
+/** Trusted deployment values the host compares with exact string equality. */
+export interface DeviceAssertionExpectedBinding {
+    readonly issuer: string;
+    readonly productId: string;
+    readonly audience: string;
+}
+/** One replay key. Every field is derived from verified claims/current authority. */
+export interface DeviceAssertionReplayConsumeInput {
+    readonly tenantId: TenantId;
+    readonly issuer: string;
+    readonly productId: string;
+    readonly deviceId: string;
+    readonly audience: string;
+    readonly jti: string;
+    readonly expiresAt: string;
+}
+/**
+ * Atomic single-use authority. `true` means this caller inserted the key;
+ * `false` means it was already consumed. Operational failures throw and must
+ * never be translated into authenticated success.
+ */
+export interface DeviceAssertionReplayAuthority {
+    consume(input: DeviceAssertionReplayConsumeInput): Promise<boolean>;
+}
+export interface AuthenticateDeviceAssertionDeps {
+    readonly verifier: DeviceAssertionVerifier;
+    readonly lookupDevice: (deviceId: string) => Promise<DeviceAssertionAuthorityRow | undefined> | DeviceAssertionAuthorityRow | undefined;
+    readonly replay: DeviceAssertionReplayAuthority;
+    readonly expected: DeviceAssertionExpectedBinding;
+    readonly now: Date;
+    readonly maxLifetimeMs?: number;
+}
+/** Audit-safe result of a consumed assertion; no credential or signature is retained. */
+export interface AuthenticatedDeviceAssertion {
+    readonly device: DevicePrincipal;
+    readonly issuer: string;
+    readonly audience: string;
+    readonly jti: string;
+    readonly issuedAt: string;
+    readonly expiresAt: string;
+}
+/**
+ * Authenticate one device assertion and atomically consume its JTI.
+ *
+ * All invalid authentication states collapse to `undefined`. Replay-store
+ * operational failures reject the promise, allowing a host to return an
+ * availability error without ever degrading to signature-only acceptance.
+ */
+export declare function authenticateDeviceAssertion(input: unknown, deps: AuthenticateDeviceAssertionDeps): Promise<AuthenticatedDeviceAssertion | undefined>;

package/dist/in-memory/device-assertion-replay.d.ts

@@ -0,0 +1,8 @@
+import type { DeviceAssertionReplayConsumeInput, DeviceAssertionReplayAuthority } from '../device-assertion';
+/** Process-local reference authority. Production runtimes need durable atomic storage. */
+export declare class InMemoryDeviceAssertionReplayAuthority implements DeviceAssertionReplayAuthority {
+    #private;
+    consume(input: DeviceAssertionReplayConsumeInput): Promise<boolean>;
+    /** Delete at most `limit` keys whose assertion lifetime ended at or before `before`. */
+    deleteExpired(before: Date, limit: number): Promise<number>;
+}

package/dist/in-memory/index.d.ts

@@ -7,6 +7,7 @@ export { InMemoryPresenceStore } from './presence';
 export { InMemoryObjectStore } from './blob';
 export { InMemoryQuotaStore } from './quota';
 export { InMemorySkillPackStore } from './skill-pack';
+export { InMemoryDeviceAssertionReplayAuthority } from './device-assertion-replay';
 export interface InMemoryCoreOptions {
     /** Defaults to a fresh {@link createMutableClock}, so TTL behavior is deterministic. */
     readonly clock?: Clock;

package/dist/index.d.ts

@@ -38,8 +38,8 @@ export type { Clock, CoreStoreName, CoreStores, MutableClock } from './stores';
 export { CORE_NON_COMPOSITION_PORT_NAMES, CORE_PORT_INTERFACES, CORE_PORT_METHODS, } from './ports-contract';
 export { DEVICE_PROOF_ALGORITHMS, DEVICE_PROOF_DOMAIN_PREFIX, DEVICE_PROOF_HEADER, DEVICE_PROOF_SCHEMA_ID, DEVICE_PROOF_VERSION, DeviceProofEnvelopeV1Schema, DeviceProofProtectedClaimsSchema, canonicalizeJson, canonicalizeJsonBytes, deviceProofCanonicalClaims, deviceProofCanonicalJson, deviceProofSigningInput, parseDeviceProofEnvelope, } from './attestation';
 export type { DeviceProofAlgorithm, DeviceProofEnvelopeV1, DeviceProofProtectedClaims, DeviceProofVerifier, DeviceProofVerifyInput, JsonObject, JsonPrimitive, JsonValue, } from './attestation';
-export { DEVICE_ASSERTION_ALGORITHMS, DEVICE_ASSERTION_AUDIENCE_MAX_BYTES, DEVICE_ASSERTION_DEFAULT_TTL_MS, DEVICE_ASSERTION_DOMAIN_PREFIX, DEVICE_ASSERTION_MAX_TTL_MS, DEVICE_ASSERTION_SCHEMA_ID, DEVICE_ASSERTION_VERSION, DeviceAssertionClaimsSchema, DeviceAssertionEnvelopeV1Schema, deviceAssertionCanonicalClaims, deviceAssertionCanonicalJson, deviceAssertionSigningInput, parseDeviceAssertionEnvelope, verifyDeviceAssertion, } from './device-assertion';
-export type { DeviceAssertionAlgorithm, DeviceAssertionClaims, DeviceAssertionDeviceRow, DeviceAssertionEnvelopeV1, DeviceAssertionVerifier, DeviceAssertionVerifyDeps, DeviceAssertionVerifyInput, } from './device-assertion';
+export { authenticateDeviceAssertion, DEVICE_ASSERTION_ALGORITHMS, DEVICE_ASSERTION_AUDIENCE_MAX_BYTES, DEVICE_ASSERTION_DEFAULT_TTL_MS, DEVICE_ASSERTION_DOMAIN_PREFIX, DEVICE_ASSERTION_MAX_TTL_MS, DEVICE_ASSERTION_SCHEMA_ID, DEVICE_ASSERTION_VERSION, DeviceAssertionClaimsSchema, DeviceAssertionEnvelopeV1Schema, deviceAssertionCanonicalClaims, deviceAssertionCanonicalJson, deviceAssertionSigningInput, parseDeviceAssertionEnvelope, verifyDeviceAssertion, } from './device-assertion';
+export type { AuthenticateDeviceAssertionDeps, AuthenticatedDeviceAssertion, DeviceAssertionAlgorithm, DeviceAssertionAuthorityRow, DeviceAssertionClaims, DeviceAssertionDeviceRow, DeviceAssertionEnvelopeV1, DeviceAssertionExpectedBinding, DeviceAssertionReplayConsumeInput, DeviceAssertionReplayAuthority, DeviceAssertionVerifier, DeviceAssertionVerifyDeps, DeviceAssertionVerifyInput, } from './device-assertion';
 export { NONCE_SIGNING_DOMAIN, nonceSigningBytes } from './pairing';
-export { IN_MEMORY_CLOCK_EPOCH, InMemoryBoardStore, InMemoryMailboxStore, InMemoryObjectStore, InMemoryPresenceStore, InMemoryQuotaStore, InMemorySkillPackStore, InMemoryTruthStore, createInMemoryCoreStores, createInMemoryCoreCompositionWithClock, createMutableClock, } from './in-memory/index';
+export { IN_MEMORY_CLOCK_EPOCH, InMemoryBoardStore, InMemoryMailboxStore, InMemoryDeviceAssertionReplayAuthority, InMemoryObjectStore, InMemoryPresenceStore, InMemoryQuotaStore, InMemorySkillPackStore, InMemoryTruthStore, createInMemoryCoreStores, createInMemoryCoreCompositionWithClock, createMutableClock, } from './in-memory/index';
 export type { InMemoryCoreComposition, InMemoryCoreOptions } from './in-memory/index';

package/dist/index.js

@@ -852,6 +852,58 @@ async function verifyDeviceAssertion(input, deps) {
   if (!verified) return void 0;
   return claims;
 }
+function isNonEmptyExactString(value) {
+  return typeof value === "string" && value.length > 0 && value.trim() === value;
+}
+function isAuthorityRow(row, requestedDeviceId) {
+  if (row === null || typeof row !== "object") return false;
+  const candidate = row;
+  return isTenantId(candidate.tenantId) && isNonEmptyExactString(candidate.productId) && candidate.deviceId === requestedDeviceId;
+}
+async function authenticateDeviceAssertion(input, deps) {
+  if (!isNonEmptyExactString(deps.expected.issuer) || !isNonEmptyExactString(deps.expected.productId) || !isNonEmptyExactString(deps.expected.audience) || utf8ByteLength(deps.expected.audience) > DEVICE_ASSERTION_AUDIENCE_MAX_BYTES) {
+    return void 0;
+  }
+  let authorityRow;
+  const claims = await verifyDeviceAssertion(input, {
+    verifier: deps.verifier,
+    lookupDevice: async (deviceId) => {
+      const row = await deps.lookupDevice(deviceId);
+      if (!isAuthorityRow(row, deviceId)) return void 0;
+      authorityRow = row;
+      return { publicKeyJwkX: row.publicKeyJwkX, revoked: row.revoked };
+    },
+    now: deps.now,
+    ...deps.maxLifetimeMs === void 0 ? {} : { maxLifetimeMs: deps.maxLifetimeMs }
+  });
+  if (claims === void 0 || authorityRow === void 0) return void 0;
+  if (claims.issuer !== deps.expected.issuer || claims.productId !== deps.expected.productId || claims.audience !== deps.expected.audience || authorityRow.productId !== deps.expected.productId || authorityRow.deviceId !== claims.deviceId) {
+    return void 0;
+  }
+  const consumed = await deps.replay.consume({
+    tenantId: authorityRow.tenantId,
+    issuer: claims.issuer,
+    productId: authorityRow.productId,
+    deviceId: authorityRow.deviceId,
+    audience: claims.audience,
+    jti: claims.jti,
+    expiresAt: claims.expiresAt
+  });
+  if (!consumed) return void 0;
+  return {
+    device: {
+      kind: "device",
+      tenantId: authorityRow.tenantId,
+      productId: authorityRow.productId,
+      deviceId: authorityRow.deviceId
+    },
+    issuer: claims.issuer,
+    audience: claims.audience,
+    jti: claims.jti,
+    issuedAt: claims.issuedAt,
+    expiresAt: claims.expiresAt
+  };
+}
 
 // src/pairing.ts
 var NONCE_SIGNING_DOMAIN = "byok-nonce-v1\n";
@@ -1895,6 +1947,44 @@ function createMutableClock(start = new Date(IN_MEMORY_CLOCK_EPOCH)) {
   };
 }
 
+// src/in-memory/device-assertion-replay.ts
+function replayKey(input) {
+  return JSON.stringify([
+    input.tenantId,
+    input.issuer,
+    input.productId,
+    input.deviceId,
+    input.audience,
+    input.jti
+  ]);
+}
+var InMemoryDeviceAssertionReplayAuthority = class {
+  #expiresAtByKey = /* @__PURE__ */ new Map();
+  async consume(input) {
+    const expiresAt = Date.parse(input.expiresAt);
+    if (!Number.isFinite(expiresAt)) throw new Error("device assertion replay expiry is invalid");
+    const key = replayKey(input);
+    if (this.#expiresAtByKey.has(key)) return false;
+    this.#expiresAtByKey.set(key, expiresAt);
+    return true;
+  }
+  /** Delete at most `limit` keys whose assertion lifetime ended at or before `before`. */
+  async deleteExpired(before, limit) {
+    const cutoff = before.getTime();
+    if (!Number.isFinite(cutoff) || !Number.isSafeInteger(limit) || limit <= 0) {
+      throw new Error("device assertion replay cleanup bounds are invalid");
+    }
+    let deleted = 0;
+    for (const [key, expiresAt] of this.#expiresAtByKey) {
+      if (expiresAt > cutoff) continue;
+      this.#expiresAtByKey.delete(key);
+      deleted += 1;
+      if (deleted === limit) break;
+    }
+    return deleted;
+  }
+};
+
 // src/in-memory/index.ts
 function createInMemoryCoreStores(options = {}) {
   const clock = options.clock ?? createMutableClock();
@@ -1915,6 +2005,6 @@ function createInMemoryCoreCompositionWithClock() {
   return { stores: createInMemoryCoreStores({ clock }).stores, clock };
 }
 
-export { BOARD_STATUSES, BOARD_TRANSITIONS, ByokCoreError, CANONICAL_TIMESTAMP_PATTERN, CAPABILITY_DECLARATION_SCHEMA_ID, CAPABILITY_NAME_PATTERN, CONTENT_HASH_PATTERN, CORE_ERROR_CODES, CORE_NON_COMPOSITION_PORT_NAMES, CORE_PORT_INTERFACES, CORE_PORT_METHODS, CORE_STORE_NAMES, CapabilityDeclarationSchema, CoreConflictError, DEVICE_ASSERTION_ALGORITHMS, DEVICE_ASSERTION_AUDIENCE_MAX_BYTES, DEVICE_ASSERTION_DEFAULT_TTL_MS, DEVICE_ASSERTION_DOMAIN_PREFIX, DEVICE_ASSERTION_MAX_TTL_MS, DEVICE_ASSERTION_SCHEMA_ID, DEVICE_ASSERTION_VERSION, DEVICE_PROOF_ALGORITHMS, DEVICE_PROOF_DOMAIN_PREFIX, DEVICE_PROOF_HEADER, DEVICE_PROOF_SCHEMA_ID, DEVICE_PROOF_VERSION, DeviceAssertionClaimsSchema, DeviceAssertionEnvelopeV1Schema, DeviceProofEnvelopeV1Schema, DeviceProofProtectedClaimsSchema, IN_MEMORY_CLOCK_EPOCH, InMemoryBoardStore, InMemoryMailboxStore, InMemoryObjectStore, InMemoryPresenceStore, InMemoryQuotaStore, InMemorySkillPackStore, InMemoryTruthStore, MAILBOX_MESSAGE_STATES, NONCE_SIGNING_DOMAIN, OBJECT_KEY_PREFIX_PATTERN, OBJECT_STATES, OBJECT_STATE_TRANSITIONS, PRESENCE_LEVELS, PRINCIPAL_KINDS, SKILL_FRONTMATTER_FIELDS, SKILL_PACK_DESCRIPTION_MAX_LENGTH, SKILL_PACK_ENTRY_PATH, SKILL_PACK_FILE_MAX_BYTES, SKILL_PACK_FILE_PATH_MAX_LENGTH, SKILL_PACK_FILE_PATH_PATTERN, SKILL_PACK_FORBIDDEN_FIELDS, SKILL_PACK_MANIFEST_SCHEMA_ID, SKILL_PACK_MAX_BYTES, SKILL_PACK_MAX_FILES, SKILL_PACK_NAME_MAX_LENGTH, SKILL_PACK_NAME_PATTERN, SKILL_PACK_REJECTIONS, SKILL_PACK_VERSION_PATTERN, STORAGE_ERROR_CODES, STORAGE_ERROR_HTTP_STATUS, STORAGE_RESERVATION_STATES, STORAGE_WRITE_KINDS, STORAGE_WRITE_POSTURES, SkillPackFileSchema, SkillPackManifestSchema, TENANT_ID_MAX_LENGTH, TENANT_KEY_SEPARATOR, TRUTH_RECORD_KINDS, assertCanonicalTimestamp, assertCapability, canonicalizeJson, canonicalizeJsonBytes, checkSkillPackEntry, checkSkillPackFileContent, checkSkillPackManifest, contentHash, createInMemoryCoreCompositionWithClock, createInMemoryCoreStores, createMutableClock, deviceAssertionCanonicalClaims, deviceAssertionCanonicalJson, deviceAssertionSigningInput, deviceProofCanonicalClaims, deviceProofCanonicalJson, deviceProofSigningInput, hasCapability, isCanonicalTimestamp, isContentHash, isControlPlanePrincipal, isCoreConflictError, isCoreError, isDevicePrincipal, isLegalBoardTransition, isLegalObjectTransition, isSkillPackPathSafe, isTenantId, nonceSigningBytes, objectKeyPrefix, parseCapabilityDeclaration, parseDeviceAssertionEnvelope, parseDeviceProofEnvelope, parseSkillFrontmatter, parseSkillPackManifest, principalTenant, skillPackContentHashInput, tenantId, tenantKey, tenantObjectKey, verifyDeviceAssertion };
+export { BOARD_STATUSES, BOARD_TRANSITIONS, ByokCoreError, CANONICAL_TIMESTAMP_PATTERN, CAPABILITY_DECLARATION_SCHEMA_ID, CAPABILITY_NAME_PATTERN, CONTENT_HASH_PATTERN, CORE_ERROR_CODES, CORE_NON_COMPOSITION_PORT_NAMES, CORE_PORT_INTERFACES, CORE_PORT_METHODS, CORE_STORE_NAMES, CapabilityDeclarationSchema, CoreConflictError, DEVICE_ASSERTION_ALGORITHMS, DEVICE_ASSERTION_AUDIENCE_MAX_BYTES, DEVICE_ASSERTION_DEFAULT_TTL_MS, DEVICE_ASSERTION_DOMAIN_PREFIX, DEVICE_ASSERTION_MAX_TTL_MS, DEVICE_ASSERTION_SCHEMA_ID, DEVICE_ASSERTION_VERSION, DEVICE_PROOF_ALGORITHMS, DEVICE_PROOF_DOMAIN_PREFIX, DEVICE_PROOF_HEADER, DEVICE_PROOF_SCHEMA_ID, DEVICE_PROOF_VERSION, DeviceAssertionClaimsSchema, DeviceAssertionEnvelopeV1Schema, DeviceProofEnvelopeV1Schema, DeviceProofProtectedClaimsSchema, IN_MEMORY_CLOCK_EPOCH, InMemoryBoardStore, InMemoryDeviceAssertionReplayAuthority, InMemoryMailboxStore, InMemoryObjectStore, InMemoryPresenceStore, InMemoryQuotaStore, InMemorySkillPackStore, InMemoryTruthStore, MAILBOX_MESSAGE_STATES, NONCE_SIGNING_DOMAIN, OBJECT_KEY_PREFIX_PATTERN, OBJECT_STATES, OBJECT_STATE_TRANSITIONS, PRESENCE_LEVELS, PRINCIPAL_KINDS, SKILL_FRONTMATTER_FIELDS, SKILL_PACK_DESCRIPTION_MAX_LENGTH, SKILL_PACK_ENTRY_PATH, SKILL_PACK_FILE_MAX_BYTES, SKILL_PACK_FILE_PATH_MAX_LENGTH, SKILL_PACK_FILE_PATH_PATTERN, SKILL_PACK_FORBIDDEN_FIELDS, SKILL_PACK_MANIFEST_SCHEMA_ID, SKILL_PACK_MAX_BYTES, SKILL_PACK_MAX_FILES, SKILL_PACK_NAME_MAX_LENGTH, SKILL_PACK_NAME_PATTERN, SKILL_PACK_REJECTIONS, SKILL_PACK_VERSION_PATTERN, STORAGE_ERROR_CODES, STORAGE_ERROR_HTTP_STATUS, STORAGE_RESERVATION_STATES, STORAGE_WRITE_KINDS, STORAGE_WRITE_POSTURES, SkillPackFileSchema, SkillPackManifestSchema, TENANT_ID_MAX_LENGTH, TENANT_KEY_SEPARATOR, TRUTH_RECORD_KINDS, assertCanonicalTimestamp, assertCapability, authenticateDeviceAssertion, canonicalizeJson, canonicalizeJsonBytes, checkSkillPackEntry, checkSkillPackFileContent, checkSkillPackManifest, contentHash, createInMemoryCoreCompositionWithClock, createInMemoryCoreStores, createMutableClock, deviceAssertionCanonicalClaims, deviceAssertionCanonicalJson, deviceAssertionSigningInput, deviceProofCanonicalClaims, deviceProofCanonicalJson, deviceProofSigningInput, hasCapability, isCanonicalTimestamp, isContentHash, isControlPlanePrincipal, isCoreConflictError, isCoreError, isDevicePrincipal, isLegalBoardTransition, isLegalObjectTransition, isSkillPackPathSafe, isTenantId, nonceSigningBytes, objectKeyPrefix, parseCapabilityDeclaration, parseDeviceAssertionEnvelope, parseDeviceProofEnvelope, parseSkillFrontmatter, parseSkillPackManifest, principalTenant, skillPackContentHashInput, tenantId, tenantKey, tenantObjectKey, verifyDeviceAssertion };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map