@femtomc/mu-control-plane 26.2.28

package/dist/idempotency_ledger.js

@@ -0,0 +1,174 @@
+import { appendJsonl, readJsonl } from "@femtomc/mu-core/node";
+import { z } from "zod";
+export const IdempotencyClaimRecordSchema = z.object({
+    key: z.string().min(1),
+    fingerprint: z.string().min(1),
+    command_id: z.string().min(1),
+    ttl_ms: z.number().int().positive(),
+    first_seen_ms: z.number().int(),
+    last_seen_ms: z.number().int(),
+    expires_at_ms: z.number().int(),
+});
+const ClaimEntrySchema = z.object({
+    kind: z.literal("claim"),
+    ts_ms: z.number().int(),
+    record: IdempotencyClaimRecordSchema,
+});
+const DuplicateEntrySchema = z.object({
+    kind: z.literal("duplicate"),
+    ts_ms: z.number().int(),
+    key: z.string().min(1),
+    fingerprint: z.string().min(1),
+    record: IdempotencyClaimRecordSchema,
+});
+const ConflictEntrySchema = z.object({
+    kind: z.literal("conflict"),
+    ts_ms: z.number().int(),
+    key: z.string().min(1),
+    incoming_fingerprint: z.string().min(1),
+    record: IdempotencyClaimRecordSchema,
+});
+export const IdempotencyLedgerEntrySchema = z.discriminatedUnion("kind", [
+    ClaimEntrySchema,
+    DuplicateEntrySchema,
+    ConflictEntrySchema,
+]);
+function cloneRecord(record) {
+    return {
+        ...record,
+    };
+}
+export class IdempotencyLedger {
+    #path;
+    #loaded = false;
+    #byKey = new Map();
+    constructor(path) {
+        this.#path = path;
+    }
+    get path() {
+        return this.#path;
+    }
+    async load() {
+        const rows = await readJsonl(this.#path);
+        this.#byKey.clear();
+        for (let idx = 0; idx < rows.length; idx++) {
+            const parsed = IdempotencyLedgerEntrySchema.safeParse(rows[idx]);
+            if (!parsed.success) {
+                throw new Error(`invalid idempotency row ${idx}: ${parsed.error.message}`);
+            }
+            const entry = parsed.data;
+            switch (entry.kind) {
+                case "claim":
+                    this.#byKey.set(entry.record.key, cloneRecord(entry.record));
+                    break;
+                case "duplicate": {
+                    const existing = this.#byKey.get(entry.key);
+                    if (existing) {
+                        this.#byKey.set(entry.key, {
+                            ...existing,
+                            last_seen_ms: Math.max(existing.last_seen_ms, entry.ts_ms),
+                        });
+                    }
+                    else {
+                        this.#byKey.set(entry.key, cloneRecord(entry.record));
+                    }
+                    break;
+                }
+                case "conflict": {
+                    if (!this.#byKey.has(entry.key)) {
+                        this.#byKey.set(entry.key, cloneRecord(entry.record));
+                    }
+                    break;
+                }
+            }
+        }
+        this.#loaded = true;
+    }
+    async #ensureLoaded() {
+        if (!this.#loaded) {
+            await this.load();
+        }
+    }
+    async lookup(key, opts = {}) {
+        await this.#ensureLoaded();
+        const nowMs = Math.trunc(opts.nowMs ?? Date.now());
+        const existing = this.#byKey.get(key);
+        if (!existing) {
+            return null;
+        }
+        if (existing.expires_at_ms <= nowMs) {
+            return null;
+        }
+        return cloneRecord(existing);
+    }
+    async claim(opts) {
+        await this.#ensureLoaded();
+        const nowMs = Math.trunc(opts.nowMs ?? Date.now());
+        const ttlMs = Math.trunc(opts.ttlMs);
+        if (!Number.isInteger(ttlMs) || ttlMs <= 0) {
+            throw new Error(`ttlMs must be a positive integer, got ${opts.ttlMs}`);
+        }
+        const existing = this.#byKey.get(opts.key);
+        if (existing && existing.expires_at_ms > nowMs) {
+            if (existing.fingerprint === opts.fingerprint) {
+                const updated = IdempotencyClaimRecordSchema.parse({
+                    ...existing,
+                    last_seen_ms: nowMs,
+                });
+                await appendJsonl(this.#path, {
+                    kind: "duplicate",
+                    ts_ms: nowMs,
+                    key: opts.key,
+                    fingerprint: opts.fingerprint,
+                    record: updated,
+                });
+                this.#byKey.set(opts.key, updated);
+                return { kind: "duplicate", record: cloneRecord(updated) };
+            }
+            await appendJsonl(this.#path, {
+                kind: "conflict",
+                ts_ms: nowMs,
+                key: opts.key,
+                incoming_fingerprint: opts.fingerprint,
+                record: existing,
+            });
+            return {
+                kind: "conflict",
+                record: cloneRecord(existing),
+                incomingFingerprint: opts.fingerprint,
+            };
+        }
+        const created = IdempotencyClaimRecordSchema.parse({
+            key: opts.key,
+            fingerprint: opts.fingerprint,
+            command_id: opts.commandId,
+            ttl_ms: ttlMs,
+            first_seen_ms: nowMs,
+            last_seen_ms: nowMs,
+            expires_at_ms: nowMs + ttlMs,
+        });
+        await appendJsonl(this.#path, {
+            kind: "claim",
+            ts_ms: nowMs,
+            record: created,
+        });
+        this.#byKey.set(opts.key, created);
+        return { kind: "created", record: cloneRecord(created) };
+    }
+    snapshot(opts = {}) {
+        const nowMs = Math.trunc(opts.nowMs ?? Date.now());
+        const out = [];
+        for (const record of this.#byKey.values()) {
+            if (record.expires_at_ms > nowMs) {
+                out.push(cloneRecord(record));
+            }
+        }
+        out.sort((a, b) => {
+            if (a.first_seen_ms !== b.first_seen_ms) {
+                return a.first_seen_ms - b.first_seen_ms;
+            }
+            return a.key.localeCompare(b.key);
+        });
+        return out;
+    }
+}

package/dist/identity_store.d.ts

@@ -0,0 +1,219 @@
+import { z } from "zod";
+import { type AssuranceTier } from "./models.js";
+export declare const ChannelSchema: z.ZodEnum<{
+    slack: "slack";
+    discord: "discord";
+    telegram: "telegram";
+}>;
+export type Channel = z.infer<typeof ChannelSchema>;
+export declare const DeprecatedChannelSchema: z.ZodEnum<{
+    imessage: "imessage";
+}>;
+export type DeprecatedChannel = z.infer<typeof DeprecatedChannelSchema>;
+export declare const CHANNEL_ASSURANCE_TIERS: {
+    readonly slack: "tier_a";
+    readonly discord: "tier_a";
+    readonly telegram: "tier_b";
+};
+export declare function assuranceTierForChannel(channel: Channel): AssuranceTier;
+export declare const IdentityBindingStatusSchema: z.ZodEnum<{
+    active: "active";
+    unlinked: "unlinked";
+    revoked: "revoked";
+}>;
+export type IdentityBindingStatus = z.infer<typeof IdentityBindingStatusSchema>;
+export declare const IdentityBindingSchema: z.ZodObject<{
+    binding_id: z.ZodString;
+    operator_id: z.ZodString;
+    channel: z.ZodEnum<{
+        slack: "slack";
+        discord: "discord";
+        telegram: "telegram";
+    }>;
+    channel_tenant_id: z.ZodString;
+    channel_actor_id: z.ZodString;
+    assurance_tier: z.ZodEnum<{
+        tier_a: "tier_a";
+        tier_b: "tier_b";
+        tier_c: "tier_c";
+    }>;
+    scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    status: z.ZodEnum<{
+        active: "active";
+        unlinked: "unlinked";
+        revoked: "revoked";
+    }>;
+    linked_at_ms: z.ZodNumber;
+    updated_at_ms: z.ZodNumber;
+    unlinked_at_ms: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    revoked_at_ms: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    revoked_by_binding_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    revoke_reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type IdentityBinding = z.infer<typeof IdentityBindingSchema>;
+export declare const IdentityLinkEntrySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"link">;
+    ts_ms: z.ZodNumber;
+    binding: z.ZodObject<{
+        binding_id: z.ZodString;
+        operator_id: z.ZodString;
+        channel: z.ZodEnum<{
+            slack: "slack";
+            discord: "discord";
+            telegram: "telegram";
+        }>;
+        channel_tenant_id: z.ZodString;
+        channel_actor_id: z.ZodString;
+        assurance_tier: z.ZodEnum<{
+            tier_a: "tier_a";
+            tier_b: "tier_b";
+            tier_c: "tier_c";
+        }>;
+        scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        status: z.ZodEnum<{
+            active: "active";
+            unlinked: "unlinked";
+            revoked: "revoked";
+        }>;
+        linked_at_ms: z.ZodNumber;
+        updated_at_ms: z.ZodNumber;
+        unlinked_at_ms: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        revoked_at_ms: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        revoked_by_binding_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        revoke_reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const IdentityUnlinkEntrySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"unlink">;
+    ts_ms: z.ZodNumber;
+    binding_id: z.ZodString;
+    actor_binding_id: z.ZodString;
+    reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const IdentityRevokeEntrySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"revoke">;
+    ts_ms: z.ZodNumber;
+    binding_id: z.ZodString;
+    actor_binding_id: z.ZodString;
+    reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const IdentityStoreEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"link">;
+    ts_ms: z.ZodNumber;
+    binding: z.ZodObject<{
+        binding_id: z.ZodString;
+        operator_id: z.ZodString;
+        channel: z.ZodEnum<{
+            slack: "slack";
+            discord: "discord";
+            telegram: "telegram";
+        }>;
+        channel_tenant_id: z.ZodString;
+        channel_actor_id: z.ZodString;
+        assurance_tier: z.ZodEnum<{
+            tier_a: "tier_a";
+            tier_b: "tier_b";
+            tier_c: "tier_c";
+        }>;
+        scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        status: z.ZodEnum<{
+            active: "active";
+            unlinked: "unlinked";
+            revoked: "revoked";
+        }>;
+        linked_at_ms: z.ZodNumber;
+        updated_at_ms: z.ZodNumber;
+        unlinked_at_ms: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        revoked_at_ms: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        revoked_by_binding_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        revoke_reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"unlink">;
+    ts_ms: z.ZodNumber;
+    binding_id: z.ZodString;
+    actor_binding_id: z.ZodString;
+    reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"revoke">;
+    ts_ms: z.ZodNumber;
+    binding_id: z.ZodString;
+    actor_binding_id: z.ZodString;
+    reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>], "kind">;
+export type IdentityStoreEntry = z.infer<typeof IdentityStoreEntrySchema>;
+export type IdentityChannelDeprecation = {
+    reason: "channel_deprecated";
+    bindingId: string;
+    channel: DeprecatedChannel;
+    tsMs: number;
+};
+export type LinkIdentityOpts = {
+    bindingId: string;
+    operatorId: string;
+    channel: Channel;
+    channelTenantId: string;
+    channelActorId: string;
+    scopes?: readonly string[];
+    nowMs?: number;
+};
+export type LinkIdentityDecision = {
+    kind: "linked";
+    binding: IdentityBinding;
+} | {
+    kind: "binding_exists";
+    binding: IdentityBinding;
+} | {
+    kind: "principal_already_linked";
+    binding: IdentityBinding;
+};
+export type UnlinkIdentityDecision = {
+    kind: "unlinked";
+    binding: IdentityBinding;
+} | {
+    kind: "not_found";
+} | {
+    kind: "invalid_actor";
+} | {
+    kind: "already_inactive";
+    binding: IdentityBinding;
+};
+export type RevokeIdentityDecision = {
+    kind: "revoked";
+    binding: IdentityBinding;
+} | {
+    kind: "not_found";
+} | {
+    kind: "already_inactive";
+    binding: IdentityBinding;
+};
+export declare class IdentityStore {
+    #private;
+    constructor(path: string);
+    get path(): string;
+    listDeprecations(): IdentityChannelDeprecation[];
+    load(): Promise<void>;
+    get(bindingId: string): IdentityBinding | null;
+    resolveActive(opts: {
+        channel: Channel;
+        channelTenantId: string;
+        channelActorId: string;
+    }): IdentityBinding | null;
+    listBindings(opts?: {
+        includeInactive?: boolean;
+    }): IdentityBinding[];
+    link(opts: LinkIdentityOpts): Promise<LinkIdentityDecision>;
+    unlinkSelf(opts: {
+        bindingId: string;
+        actorBindingId: string;
+        nowMs?: number;
+        reason?: string | null;
+    }): Promise<UnlinkIdentityDecision>;
+    revoke(opts: {
+        bindingId: string;
+        actorBindingId: string;
+        nowMs?: number;
+        reason?: string | null;
+    }): Promise<RevokeIdentityDecision>;
+}
+//# sourceMappingURL=identity_store.d.ts.map

package/dist/identity_store.d.ts.map

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