@sempdev/semp 0.4.3

package/dist/keys/compromise.js

@@ -0,0 +1,218 @@
+/**
+ * KEY.md §10.5.5 atomic identity-key rotation cascade.
+ *
+ * Revoking a device with reason `key_compromise` MUST be done in
+ * the same transaction as rotating to a new identity key plus a new
+ * encryption key — the compromised device held the shared identity
+ * private key, so the adversary holds it too. A partial cascade
+ * (device revoked but identity key not rotated) leaves the account
+ * vulnerable and is a specification violation.
+ *
+ * The bundle a revoking device produces:
+ *
+ *   1. {@link DeviceRevocation} for the compromised device, reason
+ *      `key_compromise`, signed by the prior identity key.
+ *   2. {@link SuccessorRecord} linking the prior identity key to the
+ *      new one, with `recovery_signature` and `new_key_signature`
+ *      populated. The home server fills in `domain_signature` on
+ *      receipt per RECOVERY.md §7.3.
+ *   3. New identity + new encryption public keys, fresh and ready to
+ *      publish via the account's key endpoint.
+ *   4. {@link RevocationPublication} for the prior identity key,
+ *      reason `key_compromise`, `replacement_key_id` pointing at the
+ *      new identity key, signed by the prior identity key (which the
+ *      revoking device still holds).
+ *
+ * The home server runs {@link verifyCompromiseRotation} on receipt,
+ * then commits all four artifacts atomically.
+ *
+ * @module
+ */
+import { RecordVersion as RecoveryRecordVersion, SuccessorRecordType, prepareSuccessorSignatures, signSuccessorNewKey, signSuccessorRecovery, verifySuccessorTwoSignatures, } from "../recovery/index.js";
+import { DeviceRecordVersion, DeviceRevocationType, signDeviceRevocation, verifyDeviceRevocation, } from "./device_records.js";
+import { RevocationPublicationType, RevocationVersion, signRevocationPublication, verifyRevocationPublication, } from "./key_revocation.js";
+/**
+ * Produce the four-artifact bundle a revoking device submits to the
+ * home server atomically.
+ *
+ * The successor record's `domain_signature` is left empty; the home
+ * server adds it on receipt per RECOVERY.md §7.3.
+ *
+ * Throws on missing input or signing failure.
+ */
+export function buildCompromiseRotation(input) {
+    if (input.userId === "") {
+        throw new Error("keys: rotation input missing user_id");
+    }
+    if (input.compromisedDeviceId === "") {
+        throw new Error("keys: rotation input missing compromised_device_id");
+    }
+    if (input.revokingDeviceId === "") {
+        throw new Error("keys: rotation input missing revoking_device_id");
+    }
+    if (input.priorIdentitySeed.length === 0 || input.priorIdentityKeyId === "") {
+        throw new Error("keys: rotation input missing prior identity key");
+    }
+    if (input.newIdentitySeed.length === 0 ||
+        input.newIdentityPublicKey.length === 0 ||
+        input.newIdentityKeyId === "") {
+        throw new Error("keys: rotation input missing new identity key");
+    }
+    if (input.newEncryptionPublicKey.length === 0 ||
+        input.newEncryptionKeyId === "") {
+        throw new Error("keys: rotation input missing new encryption key");
+    }
+    if (input.recoverySeed.length === 0 || input.recoveryKeyId === "") {
+        throw new Error("keys: rotation input missing recovery signing key");
+    }
+    if (input.priorIdentityKeyId === input.newIdentityKeyId) {
+        throw new Error("keys: prior and new identity fingerprints must differ");
+    }
+    const isoNow = isoSecond(input.now ?? new Date());
+    // 1. Device revocation, reason key_compromise.
+    const dev = {
+        type: DeviceRevocationType,
+        version: DeviceRecordVersion,
+        user_id: input.userId,
+        device_id: input.compromisedDeviceId,
+        reason: "key_compromise",
+        revoked_at: isoNow,
+        revoked_by_device_id: input.revokingDeviceId,
+        replacement_device_id: null,
+        signature: { algorithm: "", key_id: "", value: "" },
+    };
+    signDeviceRevocation(dev, input.priorIdentitySeed, input.priorIdentityKeyId);
+    // 2. Successor record (recovery + new_key sigs); domain_signature
+    // slot's key_id is left empty for the home server to fill in.
+    const suc = {
+        type: SuccessorRecordType,
+        version: RecoveryRecordVersion,
+        user_id: input.userId,
+        prior_key_id: input.priorIdentityKeyId,
+        new_key_id: input.newIdentityKeyId,
+        new_public_key: base64Encode(input.newIdentityPublicKey),
+        recovered_at: isoNow,
+        recovery_signature: { algorithm: "", key_id: "", value: "" },
+        new_key_signature: { algorithm: "", key_id: "", value: "" },
+        domain_signature: { algorithm: "", key_id: "", value: "" },
+    };
+    prepareSuccessorSignatures(suc, input.recoveryKeyId, input.newIdentityKeyId, "");
+    signSuccessorRecovery(suc, input.recoverySeed, input.recoveryKeyId);
+    signSuccessorNewKey(suc, input.newIdentitySeed, input.newIdentityKeyId);
+    // 3. The new public keys travel alongside the cascade; publication
+    // via the key endpoint is the home server's job.
+    // 4. Prior-identity revocation, signed by the prior identity key
+    // with reason key_compromise and replacement_key_id pointing at the
+    // new identity key.
+    const priorEntry = {
+        key_id: input.priorIdentityKeyId,
+        address: input.userId,
+        reason: "key_compromise",
+        revoked_at: isoNow,
+        replacement_key_id: input.newIdentityKeyId,
+    };
+    const prior = {
+        type: RevocationPublicationType,
+        version: RevocationVersion,
+        revoked_keys: [priorEntry],
+        signature: { algorithm: "", key_id: "", value: "" },
+    };
+    signRevocationPublication(prior, input.priorIdentitySeed, input.priorIdentityKeyId);
+    return {
+        device_revocation: dev,
+        successor: suc,
+        new_identity_public_key: input.newIdentityPublicKey,
+        new_identity_key_id: input.newIdentityKeyId,
+        new_encryption_public_key: input.newEncryptionPublicKey,
+        new_encryption_key_id: input.newEncryptionKeyId,
+        prior_identity_revocation: prior,
+    };
+}
+/**
+ * Verify every device-side signature in the cascade. The home server
+ * runs this on receipt before committing the bundle, then adds its
+ * own `domain_signature` to the successor record per RECOVERY.md §7.3.
+ *
+ * Throws on the first violation.
+ *
+ * @param c - the bundle
+ * @param priorIdentityPub - published public half of the prior
+ *   identity key (the home server resolves it from the account's
+ *   now-revoked-but-historical key set)
+ * @param recoveryVerifyPub - the `recovery_verify_pk` that the prior
+ *   identity key signed at bundle upload time per RECOVERY.md §7.5
+ *   (the home server resolves it from the prior key record)
+ */
+export function verifyCompromiseRotation(c, priorIdentityPub, recoveryVerifyPub) {
+    if (c.device_revocation === undefined || c.device_revocation === null) {
+        throw new Error("keys: rotation bundle missing device_revocation");
+    }
+    if (c.successor === undefined || c.successor === null) {
+        throw new Error("keys: rotation bundle missing successor record");
+    }
+    if (c.prior_identity_revocation === undefined ||
+        c.prior_identity_revocation === null) {
+        throw new Error("keys: rotation bundle missing prior_identity_revocation");
+    }
+    if (c.device_revocation.reason !== "key_compromise") {
+        throw new Error(`keys: rotation device revocation reason ${JSON.stringify(c.device_revocation.reason)}, want key_compromise`);
+    }
+    if (!verifyDeviceRevocation(c.device_revocation, priorIdentityPub)) {
+        throw new Error("keys: device revocation signature did not verify");
+    }
+    // Successor record: recovery_signature verifies under
+    // recoveryVerifyPub; new_key_signature verifies under the new
+    // identity public key carried inline in new_public_key;
+    // domain_signature is empty at this point.
+    let newPub;
+    try {
+        newPub = base64Decode(c.successor.new_public_key);
+    }
+    catch (err) {
+        throw new Error(`keys: decode successor new_public_key: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!verifySuccessorTwoSignatures(c.successor, recoveryVerifyPub, newPub)) {
+        throw new Error("keys: successor record two-signature verify failed");
+    }
+    if (!verifyRevocationPublication(c.prior_identity_revocation, priorIdentityPub)) {
+        throw new Error("keys: prior identity revocation signature did not verify");
+    }
+    // Cross-check: the revocation entry MUST name the prior identity
+    // key with reason key_compromise and replacement = new identity key
+    // carried inline.
+    if (c.prior_identity_revocation.revoked_keys.length !== 1) {
+        throw new Error(`keys: prior identity revocation MUST contain exactly one entry, got ${c.prior_identity_revocation.revoked_keys.length}`);
+    }
+    const entry = c.prior_identity_revocation.revoked_keys[0];
+    if (entry.reason !== "key_compromise") {
+        throw new Error(`keys: prior identity revocation entry reason ${JSON.stringify(entry.reason)}, want key_compromise`);
+    }
+    if (entry.replacement_key_id !== c.new_identity_key_id) {
+        throw new Error(`keys: prior identity revocation replacement ${JSON.stringify(entry.replacement_key_id)} does not match cascade new_identity_key_id ${JSON.stringify(c.new_identity_key_id)}`);
+    }
+}
+function isoSecond(d) {
+    return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function base64Encode(b) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(b).toString("base64");
+    }
+    let bin = "";
+    for (let i = 0; i < b.length; i++) {
+        bin += String.fromCharCode(b[i] ?? 0);
+    }
+    return btoa(bin);
+}
+function base64Decode(s) {
+    if (typeof Buffer !== "undefined") {
+        return new Uint8Array(Buffer.from(s, "base64"));
+    }
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) {
+        out[i] = bin.charCodeAt(i);
+    }
+    return out;
+}
+//# sourceMappingURL=compromise.js.map

package/dist/keys/compromise.js.map

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

package/dist/keys/device_certificate.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Scoped device certificates per KEY.md §10.3.
+ *
+ * A `SEMP_DEVICE_CERTIFICATE` binds a delegated device's public key
+ * to a permission scope and is signed by an existing full-access
+ * device of the account (the issuer). The home server enforces the
+ * scope on every relevant operation by the delegated device.
+ *
+ * This module provides:
+ *
+ *   - {@link DeviceCertificate} typed shape + the supporting
+ *     {@link Scope}, {@link ScopeMatcher}, {@link ScopeResource},
+ *     {@link ScopeEntry}, {@link RateLimitTier} types.
+ *   - {@link signDeviceCertificate}: build + Ed25519-sign a certificate
+ *     under the issuing device's signing seed (path
+ *     `signature.value`, prefix `SEMP-DEVICE-AUTHORIZE:`).
+ *   - {@link verifyDeviceCertificate}: Ed25519-verify against the
+ *     issuer's published device public key.
+ *   - {@link validateDeviceCertificate}: structural checks per
+ *     §10.3.2 / §10.3.3 / §10.3.8 (lifetime cap, scope rules).
+ *   - {@link scopeAllowsRecipient} / {@link scopeAllowsSender}:
+ *     enforcement helpers that the home server invokes on each
+ *     operation per §10.3.4.
+ *
+ * @module
+ */
+/** `type` discriminator for a device certificate. */
+export declare const DeviceCertificateType = "SEMP_DEVICE_CERTIFICATE";
+/** Domain-separation prefix for the issuer signature, per ENVELOPE.md §4.3. */
+export declare const DeviceAuthorizePrefix = "SEMP-DEVICE-AUTHORIZE:";
+/** Combined cap on `allow + deny` size in a single matcher per §10.3.3.1. */
+export declare const MaxScopeMatcherEntries = 10000;
+/** Cap on rate-limit tiers per scope field per §10.3.3.3. */
+export declare const MaxScopeRateLimitTiers = 16;
+/** Cap on certificate lifetime per §10.3.8: 365 days, in milliseconds. */
+export declare const MaxDeviceCertificateLifetimeMs: number;
+/** Matcher modes per §10.3.3.1. */
+export type MatcherMode = "unrestricted" | "restricted" | "denylist" | "none";
+/** Entity types per DELIVERY.md §5.3, reused in scope entries. */
+export type EntityType = "user" | "domain" | "server";
+/** One entry in a matcher's `allow` or `deny` list. */
+export interface ScopeEntry {
+    type: EntityType;
+    /** Required when `type === "user"`: full SEMP address. */
+    address?: string;
+    /** Required when `type === "domain"` or `type === "server"`. */
+    domain?: string;
+    /** Required when `type === "server"` (semp-go uses `domain`; this matches the spec). */
+    server?: string;
+}
+/** Rate-limit tier per §10.3.3.3. */
+export interface RateLimitTier {
+    /** Rolling-window length, MUST be >= 1. */
+    period_seconds: number;
+    /** Max ops per window, MUST be >= 0. */
+    amount_allowed: number;
+}
+/** Matcher-shape permission per §10.3.3.1, used by `scope.send` and `scope.receive`. */
+export interface ScopeMatcher {
+    mode: MatcherMode;
+    allow?: ScopeEntry[];
+    deny?: ScopeEntry[];
+    rate_limits: RateLimitTier[];
+    /** Present only on `scope.receive`. Positive integer, position in staged delivery. */
+    delivery_stage?: number;
+}
+/** Resource-shape permission per §10.3.3.2, used by blocklist/keys/devices. */
+export interface ScopeResource {
+    read: boolean;
+    write: boolean;
+    rate_limits: RateLimitTier[];
+}
+/** Five-field scope object per §10.3.3. */
+export interface Scope {
+    send: ScopeMatcher;
+    receive: ScopeMatcher;
+    blocklist: ScopeResource;
+    keys: ScopeResource;
+    devices: ScopeResource;
+}
+/** Issuer signature block. */
+export interface CertificateSignature {
+    algorithm: string;
+    key_id: string;
+    value: string;
+}
+/** SEMP_DEVICE_CERTIFICATE record per §10.3.1. */
+export interface DeviceCertificate {
+    type: typeof DeviceCertificateType;
+    version: string;
+    device_id: string;
+    device_public_key: string;
+    account: string;
+    issued_by: string;
+    issued_at: string;
+    expires_at: string;
+    scope: Scope;
+    signature: CertificateSignature;
+}
+/** Inputs to {@link signDeviceCertificate}. */
+export interface SignDeviceCertificateInput {
+    /** Pre-sign certificate; `signature.value` will be replaced. */
+    certificate: DeviceCertificate;
+    /** 32-byte Ed25519 secret seed for the issuing device. */
+    issuerSigningSeed: Uint8Array;
+    /** Lowercase-hex SHA-256 fingerprint of the issuing device public key. */
+    issuerKeyId: string;
+}
+/** Result of a successful {@link signDeviceCertificate} call. */
+export interface SignDeviceCertificateResult {
+    certificate: DeviceCertificate;
+    signatureB64: string;
+}
+/**
+ * Compute the issuer's signature over the canonical certificate
+ * bytes, then return a copy with `signature.{algorithm,key_id,value}`
+ * populated. Pre-populates the algorithm + key_id BEFORE
+ * canonicalization so the canonical bytes cover both — an attacker
+ * cannot downgrade the signing algorithm or forge a different
+ * issuer fingerprint.
+ */
+export declare function signDeviceCertificate(input: SignDeviceCertificateInput): SignDeviceCertificateResult;
+/**
+ * Ed25519-verify a certificate's signature under `issuerPub`. Returns
+ * true when the signature verifies. Does NOT cross-check that the
+ * issuer is currently a registered, non-revoked full-access device
+ * for the account — that requires a key directory store and is the
+ * caller's responsibility.
+ */
+export declare function verifyDeviceCertificate(certificate: DeviceCertificate, issuerPub: Uint8Array): boolean;
+/** Options for {@link validateDeviceCertificate}. */
+export interface ValidateOptions {
+    /**
+     * When true, don't require `signature.value` to be a non-empty
+     * string. Used during the compose path before signing.
+     */
+    skipSignatureCheck?: boolean;
+}
+/**
+ * Structural validation per §10.3.2 / §10.3.3 / §10.3.8. Throws on
+ * the first violation. Does NOT verify the signature; pair with
+ * {@link verifyDeviceCertificate}.
+ */
+export declare function validateDeviceCertificate(c: DeviceCertificate, opts?: ValidateOptions): void;
+/** Structural validation of a {@link Scope} per §10.3.3. */
+export declare function validateScope(scope: Scope): void;
+/** Sender / recipient address inputs for matcher checks. */
+export interface AddressIdentity {
+    /** Full SEMP address (e.g. `alice@example.com`). */
+    address: string;
+    /** Routing server hostname when known. */
+    server?: string;
+}
+/**
+ * Report whether `matcher` permits sending to `recipient` per
+ * §10.3.3.1. Does NOT evaluate rate limits — the caller applies
+ * rate-limit tiers separately per §10.3.4.
+ */
+export declare function scopeAllowsRecipient(matcher: ScopeMatcher, recipient: AddressIdentity): boolean;
+/**
+ * Report whether `matcher` permits receiving from `sender` per
+ * §10.3.3.1. Identical evaluation to {@link scopeAllowsRecipient};
+ * separate name reads clearly at call sites.
+ */
+export declare function scopeAllowsSender(matcher: ScopeMatcher, sender: AddressIdentity): boolean;
+//# sourceMappingURL=device_certificate.d.ts.map

package/dist/keys/device_certificate.d.ts.map

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