@krischoichoi/channel-control 0.6.0

package/README.md

@@ -0,0 +1,67 @@
+# @krischoichoi/channel-control
+
+Universal Channel Control Plane for DeepSeek Harness Channels.
+
+Mounts a Cordis service at `ctx.channelControl` that owns channel configuration,
+credentials, interactive auth sessions and runtime lifecycle. It is
+adapter-agnostic: every channel is driven through its `ChannelDefinition`, never
+through per-channel conditional code.
+
+## Install
+
+```bash
+pnpm add @krischoichoi/channel-control
+```
+
+As a Cordis plugin:
+
+```yaml
+- id: channels-control
+  name: '@krischoichoi/channel-control/plugin'
+  inject:
+    - channels
+    - credentials
+```
+
+## What it does
+
+| Manager | Responsibility |
+| --- | --- |
+| `definitions` (`ChannelDefinitionRegistry`) | Holds one `ChannelDefinition` per channel, registered by channel plugins |
+| `credentials` (`CredentialManager`) | Thin structural seam over `ctx.credentials`; secret values are never returned |
+| `auth` (`AuthSessionManager`) | Drives QR/credential auth sessions (`beginAuth`, `pollAuth`, `submitAuthInput`, `cancelAuth`) |
+| `runtime` (`ChannelRuntimeManager`) | Mounts/starts/stops/restarts adapter instances and tracks health |
+
+The service auto-starts configured channels when their definition is registered,
+and stops all mounts when the owning Cordis fiber unloads. A single
+misconfigured channel never crashes profile activation.
+
+## API surface
+
+```ts
+ctx.channelControl.listChannels();          // ChannelSummary[]
+ctx.channelControl.getSetup('qq');          // setup descriptor
+ctx.channelControl.getConfiguredState('qq');
+ctx.channelControl.saveConfig('qq', patch); // rejects secret fields
+ctx.channelControl.saveCredential('qq', 'appSecret', value);
+ctx.channelControl.applySetup('qq', input); // transactional setup + reconcile
+ctx.channelControl.beginAuth('weixin', input);
+ctx.channelControl.pollAuth(sessionId);
+```
+
+## Development
+
+```bash
+pnpm --filter @krischoichoi/channel-control build
+pnpm --filter @krischoichoi/channel-control typecheck
+pnpm --filter @krischoichoi/channel-control test
+```
+
+## Related
+
+- [Repository root](../../README.md)
+- [Architecture design](../../docs/architecture.md)
+
+## License
+
+[MIT](../../LICENSE)

package/lib/access/conversation-directory-store.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Conversation Identity Directory — durable store for the
+ * discovered canonical conversation identities plus optional display metadata.
+ *
+ * This is identity METADATA only (plan §13). It must never contain message
+ * content, attachments, raw events, secrets, or any authorization state: the
+ * Access Gate keeps exact-matching `conversation.id`; the directory only lets
+ * the Web choose previously observed group OpenIDs for policy authoring.
+ *
+ * Records are keyed per `channelId + accountId` (plan §24/§25), so identities
+ * observed under account A can never leak into account B.
+ */
+import type { ChannelStorage } from '@krischoichoi/channel-core';
+/** One observed conversation identity (plan §6). */
+export interface ConversationIdentityEntry {
+    channelId: string;
+    accountId: string;
+    /**
+     * Runtime canonical conversation id (QQ group: `group_openid`) — the only
+     * authorization key.
+     */
+    canonicalId: string;
+    type: 'group';
+    /**
+     * Optional human/platform-facing identifier. Display metadata only — never
+     * an authorization key.
+     */
+    externalId?: string;
+    /** Human-readable title observed by the adapter, when the platform provides one. */
+    displayName?: string;
+    /** Local, operator-facing alias. */
+    alias?: string;
+    /** Opaque non-secret provider/application scope; never part of the Web DTO. */
+    scopeFingerprint?: string;
+    /**
+     * Set when the same canonicalId was later observed with a DIFFERENT
+     * externalId (plan §23). The latest externalId is kept and the conflict is
+     * surfaced for re-confirmation; authorization is never changed by it.
+     */
+    identityConflict?: boolean;
+    firstSeenAt: number;
+    lastSeenAt: number;
+}
+/** Stored record shape under one channel+account (versioned, plan §25). */
+export interface ConversationDirectoryRecord {
+    version: 1;
+    conversations: Record<string, ConversationIdentityEntry>;
+}
+/** Durable conversation-directory store abstraction. */
+export interface ConversationDirectoryStore {
+    get(channelId: string, accountId: string): Promise<ConversationDirectoryRecord | undefined>;
+    set(channelId: string, accountId: string, record: ConversationDirectoryRecord): Promise<void>;
+}
+/**
+ * Storage key for one channel+account's directory record. Scoped to the
+ * channel-control domain — consumers outside this package (web) go through the
+ * control API, never this key format.
+ */
+export declare function conversationDirectoryStorageKey(channelId: string, accountId: string): string;
+/** Durable store backed by the shared channel-domain [ChannelStorage]. */
+export declare class ChannelStorageConversationDirectoryStore implements ConversationDirectoryStore {
+    private readonly getStorage;
+    constructor(getStorage: () => ChannelStorage);
+    get(channelId: string, accountId: string): Promise<ConversationDirectoryRecord | undefined>;
+    set(channelId: string, accountId: string, record: ConversationDirectoryRecord): Promise<void>;
+}
+/** In-memory store (tests / transient default); state is lost on restart. */
+export declare class MemoryConversationDirectoryStore implements ConversationDirectoryStore {
+    private readonly values;
+    get(channelId: string, accountId: string): Promise<ConversationDirectoryRecord | undefined>;
+    set(channelId: string, accountId: string, record: ConversationDirectoryRecord): Promise<void>;
+}
+//# sourceMappingURL=conversation-directory-store.d.ts.map

package/lib/access/conversation-directory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-directory-store.d.ts","sourceRoot":"","sources":["../../src/access/conversation-directory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGjE,oDAAoD;AACpD,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,2EAA2E;AAC3E,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,CAAC,CAAC;IACX,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;CAC1D;AAkCD,wDAAwD;AACxD,MAAM,WAAW,0BAA0B;IACzC,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC,CAAC;IAC5F,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/F;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5F;AAED,0EAA0E;AAC1E,qBAAa,wCAAyC,YAAW,0BAA0B;IACzF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;gBAEtC,UAAU,EAAE,MAAM,cAAc;IAItC,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC;IAM3F,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;CAMpG;AAED,6EAA6E;AAC7E,qBAAa,gCAAiC,YAAW,0BAA0B;IACjF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkD;IAEnE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC;IAI3F,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;CAGpG"}

package/lib/access/conversation-directory-store.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+const entrySchema = z.object({
+    channelId: z.string().min(1),
+    accountId: z.string().min(1),
+    canonicalId: z.string().min(1),
+    type: z.literal('group'),
+    externalId: z.string().min(1).optional(),
+    displayName: z.string().min(1).optional(),
+    alias: z.string().min(1).optional(),
+    scopeFingerprint: z.string().min(1).optional(),
+    identityConflict: z.boolean().optional(),
+    firstSeenAt: z.number(),
+    lastSeenAt: z.number(),
+}).loose();
+const recordSchema = z.object({
+    version: z.literal(1),
+    conversations: z.record(z.string().min(1), entrySchema),
+}, {
+    error: 'conversation directory record must be a v1 record',
+});
+function parseRecord(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = recordSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * Storage key for one channel+account's directory record. Scoped to the
+ * channel-control domain — consumers outside this package (web) go through the
+ * control API, never this key format.
+ */
+export function conversationDirectoryStorageKey(channelId, accountId) {
+    return `conversation-directory:v1:${encodeURIComponent(channelId)}:${encodeURIComponent(accountId)}`;
+}
+/** Durable store backed by the shared channel-domain [ChannelStorage]. */
+export class ChannelStorageConversationDirectoryStore {
+    getStorage;
+    constructor(getStorage) {
+        this.getStorage = getStorage;
+    }
+    async get(channelId, accountId) {
+        const raw = await this.getStorage().get(conversationDirectoryStorageKey(channelId, accountId));
+        if (raw === undefined)
+            return undefined;
+        return parseRecord(raw);
+    }
+    async set(channelId, accountId, record) {
+        await this.getStorage().set(conversationDirectoryStorageKey(channelId, accountId), JSON.stringify(record));
+    }
+}
+/** In-memory store (tests / transient default); state is lost on restart. */
+export class MemoryConversationDirectoryStore {
+    values = new Map();
+    async get(channelId, accountId) {
+        return this.values.get(conversationDirectoryStorageKey(channelId, accountId));
+    }
+    async set(channelId, accountId, record) {
+        this.values.set(conversationDirectoryStorageKey(channelId, accountId), record);
+    }
+}
+//# sourceMappingURL=conversation-directory-store.js.map

package/lib/access/conversation-directory-store.js.map

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

package/lib/access/conversation-directory.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ConversationDirectory — observes canonical channel events and maintains the
+ * human identifier ↔ canonical conversation id mapping (plan §12).
+ *
+ * The observer consumes ONLY the canonical event surface
+ * (`conversation.id` / `conversation.type` / `conversation.externalId` /
+ * `conversation.name`) — it never sees or parses a platform raw payload. The
+ * adapter is responsible for having validated `externalId` at its trust
+ * boundary.
+ *
+ * Authorization is untouched by everything in this file: the directory stores
+ * identity metadata, and the Access Gate keeps exact-matching the canonical
+ * `conversation.id`.
+ */
+import type { ChannelEvent, ChannelLogger } from '@krischoichoi/channel-core';
+import type { PublicConversationIdentity } from '../types.js';
+import type { ConversationDirectoryStore, ConversationIdentityEntry } from './conversation-directory-store.js';
+/** Project a stored entry onto the sanitized Web DTO (drops scope bookkeeping). */
+export declare function toPublicConversationIdentity(entry: ConversationIdentityEntry): PublicConversationIdentity;
+export interface ConversationDirectoryOptions {
+    store: ConversationDirectoryStore;
+    /** Injectable clock (ms since epoch). Defaults to Date.now. */
+    now?: () => number;
+    logger?: Pick<ChannelLogger, 'warn'>;
+}
+export declare class ConversationDirectory {
+    private readonly store;
+    private readonly now;
+    private readonly logger;
+    /** Serializes read-modify-write cycles per channel+account. */
+    private readonly chains;
+    constructor(options: ConversationDirectoryOptions);
+    /**
+   * Observe one canonical event. Every group message creates or refreshes its
+   * canonical identity; `externalId`, when a platform actually provides one,
+   * is optional display metadata only.
+     * Never throws — a directory failure must not break the inbound loop.
+     */
+    observe(event: ChannelEvent, scopeFingerprint?: string, scopeRequired?: boolean): void;
+    /** All observed conversation identities for one channel+account. */
+    list(channelId: string, accountId?: string, scopeFingerprint?: string, scopeRequired?: boolean): Promise<ConversationIdentityEntry[]>;
+    /**
+     * Resolve an optional platform-facing identifier to an observed canonical
+     * entry. QQ does not use this path: its Web UI selects discovered canonical
+     * group OpenIDs directly.
+     */
+    resolveByExternalId(channelId: string, externalId: string | undefined, accountId?: string, scopeFingerprint?: string, scopeRequired?: boolean): Promise<ConversationIdentityEntry | undefined>;
+    /** Read-modify-write one mapping under the channel+account scope. */
+    private record;
+}
+//# sourceMappingURL=conversation-directory.d.ts.map

package/lib/access/conversation-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-directory.d.ts","sourceRoot":"","sources":["../../src/access/conversation-directory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EACV,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,mCAAmC,CAAC;AAE3C,mFAAmF;AACnF,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,yBAAyB,GAC/B,0BAA0B,CAW5B;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,0BAA0B,CAAC;IAClC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;gBAE/C,OAAO,EAAE,4BAA4B;IAMjD;;;;;OAKG;IACH,OAAO,CACL,KAAK,EAAE,YAAY,EACnB,gBAAgB,CAAC,EAAE,MAAM,EACzB,aAAa,UAAQ,GACpB,IAAI;IA+BP,oEAAoE;IAC9D,IAAI,CACR,SAAS,EAAE,MAAM,EACjB,SAAS,SAAS,EAClB,gBAAgB,CAAC,EAAE,MAAM,EACzB,aAAa,UAAQ,GACpB,OAAO,CAAC,yBAAyB,EAAE,CAAC;IAevC;;;;OAIG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,SAAS,SAAS,EAClB,gBAAgB,CAAC,EAAE,MAAM,EACzB,aAAa,UAAQ,GACpB,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC;IAUjD,qEAAqE;YACvD,MAAM;CA6CrB"}

package/lib/access/conversation-directory.js

@@ -0,0 +1,118 @@
+/** Project a stored entry onto the sanitized Web DTO (drops scope bookkeeping). */
+export function toPublicConversationIdentity(entry) {
+    return {
+        type: entry.type,
+        canonicalId: entry.canonicalId,
+        ...(entry.externalId ? { externalId: entry.externalId } : {}),
+        ...(entry.displayName ? { displayName: entry.displayName } : {}),
+        ...(entry.alias ? { alias: entry.alias } : {}),
+        ...(entry.identityConflict ? { identityConflict: true } : {}),
+        firstSeenAt: entry.firstSeenAt,
+        lastSeenAt: entry.lastSeenAt,
+    };
+}
+export class ConversationDirectory {
+    store;
+    now;
+    logger;
+    /** Serializes read-modify-write cycles per channel+account. */
+    chains = new Map();
+    constructor(options) {
+        this.store = options.store;
+        this.now = options.now ?? Date.now;
+        this.logger = options.logger ?? { warn: () => { } };
+    }
+    /**
+   * Observe one canonical event. Every group message creates or refreshes its
+   * canonical identity; `externalId`, when a platform actually provides one,
+   * is optional display metadata only.
+     * Never throws — a directory failure must not break the inbound loop.
+     */
+    observe(event, scopeFingerprint, scopeRequired = false) {
+        if (event.type !== 'message.received')
+            return;
+        if (event.conversation.type !== 'group')
+            return;
+        // A scope-aware channel without an active provider/application scope must
+        // not create an unscoped entry. Unscoped entries remain valid only for
+        // channels that do not declare provider scoping at all.
+        if (scopeRequired && scopeFingerprint === undefined)
+            return;
+        const { channel: channelId, accountId, conversation } = event;
+        const key = `${channelId}\u0000${accountId}`;
+        const chain = (this.chains.get(key) ?? Promise.resolve())
+            .then(() => this.record(channelId, accountId, conversation.id, conversation.externalId, conversation.name, scopeFingerprint))
+            .catch((error) => {
+            this.logger.warn(`[channel-control] conversation directory observe failed for '${channelId}:${accountId}'`, error);
+        })
+            .finally(() => {
+            // Drop the chain once it is the tail so the map does not grow forever.
+            if (this.chains.get(key) === chain)
+                this.chains.delete(key);
+        });
+        this.chains.set(key, chain);
+    }
+    /** All observed conversation identities for one channel+account. */
+    async list(channelId, accountId = 'main', scopeFingerprint, scopeRequired = false) {
+        const record = await this.store.get(channelId, accountId);
+        return Object.values(record?.conversations ?? {})
+            // A channel declaring an active provider scope must never resolve an
+            // unscoped or differently scoped historical entry. This deliberately
+            // makes pre-scope records re-discoverable rather than risking a cross-Bot
+            // group_openid reuse after an AppID change.
+            .filter((entry) => {
+            if (!scopeRequired)
+                return true;
+            if (scopeFingerprint === undefined)
+                return false;
+            return entry.scopeFingerprint === scopeFingerprint;
+        })
+            .sort((a, b) => b.lastSeenAt - a.lastSeenAt);
+    }
+    /**
+     * Resolve an optional platform-facing identifier to an observed canonical
+     * entry. QQ does not use this path: its Web UI selects discovered canonical
+     * group OpenIDs directly.
+     */
+    async resolveByExternalId(channelId, externalId, accountId = 'main', scopeFingerprint, scopeRequired = false) {
+        const entries = await this.list(channelId, accountId, scopeFingerprint, scopeRequired);
+        return entries.find((entry) => entry.externalId === externalId);
+    }
+    /** Read-modify-write one mapping under the channel+account scope. */
+    async record(channelId, accountId, canonicalId, externalId, displayName, scopeFingerprint) {
+        const record = (await this.store.get(channelId, accountId)) ?? {
+            version: 1,
+            conversations: {},
+        };
+        const now = this.now();
+        const existing = record.conversations[canonicalId];
+        if (!existing) {
+            record.conversations[canonicalId] = {
+                channelId,
+                accountId,
+                canonicalId,
+                type: 'group',
+                ...(externalId ? { externalId } : {}),
+                ...(displayName ? { displayName } : {}),
+                ...(scopeFingerprint ? { scopeFingerprint } : {}),
+                firstSeenAt: now,
+                lastSeenAt: now,
+            };
+        }
+        else {
+            const conflict = externalId !== undefined &&
+                existing.externalId !== undefined &&
+                existing.externalId !== externalId;
+            record.conversations[canonicalId] = {
+                ...existing,
+                ...(externalId ? { externalId } : {}),
+                ...(displayName ? { displayName } : {}),
+                ...(scopeFingerprint ? { scopeFingerprint } : {}),
+                ...(conflict ? { identityConflict: true } : {}),
+                lastSeenAt: now,
+            };
+        }
+        await this.store.set(channelId, accountId, record);
+    }
+}
+//# sourceMappingURL=conversation-directory.js.map

package/lib/access/conversation-directory.js.map

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

package/lib/access/manager.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ChannelAccessManager — the control-plane owner of a channel's access state.
+ *
+ * Responsibilities:
+ * - read a channel's declared access descriptor from its definition.
+ * - compute access readiness from the stored policy + descriptor + owner
+ *   discovery, including safe owner bootstrap for `ownerDiscovery='account'`
+ *   channels (missing policy + resolvable account owner -> materialize
+ *   and persist owner-only, then report ready).
+ * - validate + persist a policy via `saveAccess`.
+ *
+ * No secret ever passes through here: only canonical sender/group IDs.
+ */
+import type { ChannelLogger, ChannelAccessPolicy } from '@krischoichoi/channel-core';
+import { ChannelDefinitionRegistry } from '../definitions/registry.js';
+import type { ChannelAccessState } from '../types.js';
+import type { ChannelAccessPolicyStore } from './policy-store.js';
+/** A store that can also expose the raw stored string (for missing-vs-invalid). */
+export type ReadableChannelAccessPolicyStore = ChannelAccessPolicyStore & {
+    getRaw?(channelId: string, accountId: string): Promise<string | undefined>;
+};
+export interface ChannelAccessManagerOptions {
+    registry: ChannelDefinitionRegistry;
+    store: ReadableChannelAccessPolicyStore;
+    /**
+     * Resolve the account owner's canonical sender.id for a channel. For
+     * `ownerDiscovery='account'` channels this drives owner bootstrap; it is a
+     * no-op (returns undefined) for channels that do not implement it.
+     */
+    resolveOwnerIdentity(channelId: string, accountId: string): Promise<string | undefined>;
+    logger?: Pick<ChannelLogger, 'info' | 'warn'>;
+}
+export declare class ChannelAccessManager {
+    private readonly registry;
+    private readonly store;
+    private readonly resolveOwnerIdentity;
+    private readonly logger;
+    constructor(options: ChannelAccessManagerOptions);
+    /** Compute the access state for one channel+account. */
+    getState(channelId: string, accountId?: string): Promise<ChannelAccessState>;
+    /** Validate + persist a policy, then return the resulting access state. */
+    saveAccess(channelId: string, policy: ChannelAccessPolicy, accountId?: string): Promise<ChannelAccessState>;
+    private buildState;
+    /** Simple owner-source heuristic. No secrets involved. */
+    private deriveOwner;
+}
+//# sourceMappingURL=manager.d.ts.map

package/lib/access/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/access/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAEvE,OAAO,KAAK,EAGV,kBAAkB,EACnB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAIlE,mFAAmF;AACnF,MAAM,MAAM,gCAAgC,GAAG,wBAAwB,GAAG;IACxE,MAAM,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC5E,CAAC;AAEF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,yBAAyB,CAAC;IACpC,KAAK,EAAE,gCAAgC,CAAC;IACxC;;;;OAIG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACxF,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAC/C;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAsD;IAC3F,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;gBAElD,OAAO,EAAE,2BAA2B;IAOhD,wDAAwD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6ElF,2EAA2E;IACrE,UAAU,CACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,mBAAmB,EAC3B,SAAS,SAAS,GACjB,OAAO,CAAC,kBAAkB,CAAC;IAa9B,OAAO,CAAC,UAAU;IAclB,0DAA0D;IAC1D,OAAO,CAAC,WAAW;CAiBpB"}

package/lib/access/manager.js

@@ -0,0 +1,124 @@
+import { ChannelDefinitionRegistry } from '../definitions/registry.js';
+import { ControlError } from '../errors.js';
+import { ownerOnlyPolicy, platformPrivatePolicy } from './materialize.js';
+import { validateAccessPolicy } from './validation.js';
+export class ChannelAccessManager {
+    registry;
+    store;
+    resolveOwnerIdentity;
+    logger;
+    constructor(options) {
+        this.registry = options.registry;
+        this.store = options.store;
+        this.resolveOwnerIdentity = options.resolveOwnerIdentity;
+        this.logger = options.logger ?? { info: () => { }, warn: () => { } };
+    }
+    /** Compute the access state for one channel+account. */
+    async getState(channelId, accountId = 'main') {
+        const definition = this.registry.require(channelId);
+        const descriptor = definition.access;
+        const stored = await this.store.get(channelId, accountId);
+        if (stored) {
+            if (descriptor.ownerDiscovery === 'platform' && !stored.ownerId) {
+                const ownerId = await this.resolveOwnerIdentity(channelId, accountId);
+                if (ownerId) {
+                    const next = { ...stored, ownerId };
+                    await this.store.set(channelId, accountId, next);
+                    return this.buildState(descriptor, 'ready', next, {
+                        configured: true,
+                        id: ownerId,
+                        source: 'platform',
+                    });
+                }
+            }
+            if (descriptor.ownerDiscovery === 'platform' && stored.ownerId) {
+                const ownerId = await this.resolveOwnerIdentity(channelId, accountId);
+                if (ownerId === undefined) {
+                    // A platform-scoped owner can disappear when the provider AppID is
+                    // rotated. Do not let the previous bot's owner grant remain usable.
+                    const { ownerId: _staleOwner, ...withoutOwner } = stored;
+                    await this.store.set(channelId, accountId, withoutOwner);
+                    return this.buildState(descriptor, 'ready', withoutOwner);
+                }
+            }
+            // A valid policy present -> ready.
+            return this.buildState(descriptor, 'ready', stored);
+        }
+        // `get` returned undefined: distinguish an actually-missing policy from a
+        // stored-but-invalid one (non-empty raw that fails to parse).
+        const raw = await this.store.getRaw?.(channelId, accountId);
+        if (raw !== undefined) {
+            // Stored raw exists but fails the schema -> invalid-policy (fail closed).
+            return this.buildState(descriptor, 'invalid-policy', undefined);
+        }
+        // No policy at all.
+        // ownerDiscovery='account' -> safe owner bootstrap.
+        if (descriptor.ownerDiscovery === 'account') {
+            const ownerId = await this.resolveOwnerIdentity(channelId, accountId);
+            if (ownerId) {
+                const policy = ownerOnlyPolicy(ownerId);
+                await this.store.set(channelId, accountId, policy);
+                this.logger.info(`[channel-control] access policy bootstrapped (channel=${channelId}, account=${accountId}, operation=owner-bootstrap, preset=owner-only, readiness=ready)`);
+                return this.buildState(descriptor, 'ready', policy, {
+                    configured: true,
+                    id: ownerId,
+                    source: 'account',
+                });
+            }
+            // Account channel but no owner resolvable yet (e.g. no credential).
+            return this.buildState(descriptor, 'missing-policy', undefined);
+        }
+        // Platform-private channels guarantee that C2C messages can only originate
+        // from the bot creator. Materialize that narrow grant, never opening groups.
+        if (descriptor.ownerDiscovery === 'platform') {
+            const ownerId = await this.resolveOwnerIdentity(channelId, accountId);
+            const policy = platformPrivatePolicy(ownerId);
+            await this.store.set(channelId, accountId, policy);
+            this.logger.info(`[channel-control] access policy bootstrapped (channel=${channelId}, account=${accountId}, operation=platform-bootstrap, preset=custom, readiness=ready)`);
+            return this.buildState(descriptor, 'ready', policy, ownerId
+                ? { configured: true, id: ownerId, source: 'platform' }
+                : undefined);
+        }
+        // Non-account owner discovery with no policy.
+        if (descriptor.ownerDiscovery === 'claim') {
+            return this.buildState(descriptor, 'needs-owner', undefined);
+        }
+        return this.buildState(descriptor, 'missing-policy', undefined);
+    }
+    /** Validate + persist a policy, then return the resulting access state. */
+    async saveAccess(channelId, policy, accountId = 'main') {
+        const definition = this.registry.require(channelId);
+        const result = validateAccessPolicy(policy, definition.access);
+        if (!result.ok) {
+            this.logger.warn(`[channel-control] access policy rejected (channel=${channelId}, account=${accountId}, operation=save, reason=validation)`);
+            throw new ControlError('INVALID_ACCESS_POLICY', result.error);
+        }
+        await this.store.set(channelId, accountId, result.policy);
+        const state = await this.getState(channelId, accountId);
+        this.logger.info(`[channel-control] access policy saved (channel=${channelId}, account=${accountId}, operation=save, preset=${result.policy.preset}, dmPolicy=${result.policy.dmPolicy}, groupPolicy=${result.policy.groupPolicy}, readiness=${state.readiness})`);
+        return state;
+    }
+    buildState(descriptor, readiness, policy, ownerOverride) {
+        return {
+            descriptor,
+            readiness,
+            policy,
+            owner: ownerOverride ?? this.deriveOwner(policy, descriptor),
+        };
+    }
+    /** Simple owner-source heuristic. No secrets involved. */
+    deriveOwner(policy, descriptor) {
+        if (policy?.ownerId) {
+            const source = descriptor.ownerDiscovery === 'account'
+                ? 'account'
+                : descriptor.ownerDiscovery === 'claim'
+                    ? 'claim'
+                    : descriptor.ownerDiscovery === 'platform'
+                        ? 'platform'
+                        : 'manual';
+            return { configured: true, id: policy.ownerId, source };
+        }
+        return { configured: false };
+    }
+}
+//# sourceMappingURL=manager.js.map

package/lib/access/manager.js.map

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

package/lib/access/materialize.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Policy materialization helpers.
+ *
+ * `ownerOnlyPolicy` builds the canonical owner-only materialization:
+ *   dmPolicy=allowlist, allowFrom=[ownerId], groupPolicy=disabled, groups={}.
+ *
+ * `rebindOwner` handles an owner change (new local operator claims/rotates):
+ * - owner-only: re-materialize allowFrom=[newOwner] (the old sole grant disappears).
+ * - allowlist/custom: update ownerId only; leave allowFrom/groups untouched so a
+ *   re-scan / re-claim never silently rewrites a *complex* user-defined policy.
+ */
+import type { ChannelAccessPolicy } from '@krischoichoi/channel-core';
+/** Keep the persisted policy aligned with its user-facing preset. */
+export declare function materializeAccessPolicy(policy: ChannelAccessPolicy): ChannelAccessPolicy;
+/** The canonical owner-only policy materialization. */
+export declare function ownerOnlyPolicy(ownerId: string): ChannelAccessPolicy;
+/**
+ * Private messages are platform-restricted to the bot creator. Group access
+ * remains disabled until the local operator explicitly configures it.
+ *
+ * Used only when the channel declares ownerDiscovery='platform': the upstream
+ * platform itself restricts the private-chat audience (e.g. QQ C2C is limited
+ * to the bot creator). `dmPolicy: 'open'` therefore means "accept every DM
+ * the platform can deliver", NOT "every platform user can start a DM".
+ */
+export declare function platformPrivatePolicy(ownerId?: string): ChannelAccessPolicy;
+/**
+ * Rebind a policy to a new owner identity. Returns a NEW policy
+ * object; the input is never mutated. When `newOwner` is empty this is a no-op
+ * returning the input unchanged (callers guard upstream).
+ */
+export declare function rebindOwner(policy: ChannelAccessPolicy, newOwner: string): ChannelAccessPolicy;
+//# sourceMappingURL=materialize.d.ts.map

package/lib/access/materialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../../src/access/materialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,qEAAqE;AACrE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAUxF;AAED,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAUpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAU3E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,EAAE,MAAM,GACf,mBAAmB,CAiBrB"}