@sema-agent/server 7.10.0 → 7.12.0

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -0,0 +1,249 @@
+import { type PersistedAllowRule, type PermissionRuleStore, type PermissionRuleStoreProvider, type PutResult, type QuarantinedRuleAdd, type RuleAdd, type RuleDot, type RuleScope, type RuleSyncFrontier, type RuleTombstone, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleOwner } from "@sema-agent/core";
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { PgQueryFn } from "./pg-query.js";
+import { type SqlDriver } from "./sql-driver.js";
+import type { Pool as PgPool } from "pg";
+/** core `permission-rule-store.ts` 的 `PERMISSION_RULE_WRITER` 字面值(逐字)。`writerOf(store)` 读的
+ *  就是这把键——它是 core 与 backend 之间**事实上的**协议名,只是没被导出。 */
+export declare const PERMISSION_RULE_WRITER_KEY = "__semaPermissionRuleWriter";
+/** core `RedemptionAuthorization` 的镜像。 */
+export interface RedemptionAuthorizationMirror {
+    recordId: string;
+    principal?: string;
+    owner?: RuleOwner;
+}
+/** core `RuleAddDelta` 的镜像。 */
+export interface RuleAddDeltaMirror {
+    kind: "redemption-add";
+    rule: string;
+    scope: RuleScope;
+    tool: PersistedAllowRule["tool"];
+    match: PersistedAllowRule["match"];
+    command: string;
+    add: RuleAdd;
+    redemption: RedemptionAuthorizationMirror;
+}
+/** core `RuleDeleteDelta` 的镜像。 */
+export interface RuleDeleteDeltaMirror {
+    kind: "tighten-delete";
+    tombstone: RuleTombstone;
+}
+/** core `RuleSyncJoinDelta` 的镜像(**本 backend 不实现**,只为判别式完整——见顶注 ②)。 */
+export interface RuleSyncJoinDeltaMirror {
+    kind: "sync-join";
+    inbound: {
+        rules: PersistedAllowRule[];
+        tombstones: RuleTombstone[];
+    };
+    gcFrontier?: RuleSyncFrontier;
+    observedVector?: RuleSyncFrontier;
+    quarantine?: Array<{
+        rule: string;
+        scope: RuleScope;
+        dots: RuleDot[];
+        reason: QuarantinedRuleAdd["reason"];
+    }>;
+}
+export type RuleWriteDeltaMirror = RuleAddDeltaMirror | RuleDeleteDeltaMirror | RuleSyncJoinDeltaMirror;
+/** core `RawRuleSyncState` 的镜像。 */
+export interface RawRuleSyncStateMirror {
+    actor: string;
+    counter: number;
+    rev: number;
+    rules: PersistedAllowRule[];
+    tombstones: RuleTombstone[];
+    observedVector?: RuleSyncFrontier;
+    quarantined?: QuarantinedRuleAdd[];
+}
+/** core `PermissionRuleWriter` 的镜像。 */
+export interface PermissionRuleWriterMirror {
+    nextDot(): Promise<RuleDot>;
+    apply(delta: RuleWriteDeltaMirror, opts: {
+        expectedRev: number;
+    }): Promise<PutResult | {
+        conflict: true;
+        rev: number;
+    }>;
+    readRaw(): Promise<RawRuleSyncStateMirror>;
+}
+/** core `WritablePermissionRuleStore` 的镜像(属性名 = {@link PERMISSION_RULE_WRITER_KEY})。 */
+export interface WritablePermissionRuleStoreMirror extends PermissionRuleStore {
+    readonly __semaPermissionRuleWriter: PermissionRuleWriterMirror;
+}
+/**
+ * core 私有 `writerOf` 的**本地对偶**:一只店的写面,或 `undefined`(该 backend 从引擎侧看是只读的)。
+ *
+ * 结构检查而不是断言 —— 它同时是本仓消费点(测试/诊断)读写面的**唯一**入口:没有这个函数,每个调用点
+ * 都会各写一次 `as unknown as {…}`,那既是三处宽松断言,也是三份会各自漂的形状假设。
+ */
+export declare function writerOfSqlRuleStore(store: PermissionRuleStore): PermissionRuleWriterMirror | undefined;
+export declare const PERMISSION_RULE_TABLE = "permission_rule";
+export declare const PERMISSION_RULE_APPROVAL_TABLE = "permission_rule_approval";
+export declare const PERMISSION_RULE_TICKET_TABLE = "permission_rule_ticket";
+/**
+ * MySQL-protocol(TiDB)侧的三条建表语句。真源在本文件(与 PG twin 并排,方言差异一眼可对);
+ * `tidb-pool.ts` 的 `SCHEMA_STATEMENTS` 用 `...TIDB_PERMISSION_RULE_STATEMENTS` 展开,于是三张表跟着
+ * 中央 `ensureSchema` 在 **named-lock 的那条 conn** 上建(同 `TIDB_APPROVAL_ASK_STATEMENTS` 先例)。
+ *
+ * 列宽依据(#192 A10 的「每列的值由谁铸、有没有入口上限」口径):
+ *  · `owner_key` / `record_id` / `ticket_id` / `approval_id` / `payload_hash` / `checksum` → 190:
+ *    全是本仓自铸的键类值(sha256 hex 64 / uuid 36 / `sha256:` 前缀 71),190 是全仓键轴的统一宽度。
+ *  · `principal` → 512:principal 入口上限是 `PRINCIPAL_MAX_LENGTH = 190`(`security.ts`),这里给
+ *    名类宽度 512 是**上界宽于入口**的方向(绝不制造静默截断面)。
+ *  · `actor` → 190:本 backend 自铸的副本身份(`sql-<12 hex>`),按构造 ≤ 20 字符。
+ *  · 内容列一律 LONGTEXT / TEXT:一只桶的规则集没有硬上限(导入一份大 settings 就能过 64K TEXT 墙)。
+ *  · 毫秒列一律 `_ms` 后缀;OCC 列一律叫 `rev`(`version` 是形/schema 版本的保留词)。
+ */
+export declare const TIDB_PERMISSION_RULE_STATEMENTS: readonly string[];
+/** {@link TIDB_PERMISSION_RULE_STATEMENTS} 的遍历壳(生产路径走 `tidb-pool.ts` 中央 `ensureSchema`;
+ *  本函数留给只需要这三张表的集成测试)。 */
+export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise<void>;
+export declare function ensurePgPermissionRuleSchema(q: PgQueryFn): Promise<void>;
+/**
+ * 一只桶的**存储键**(纯数据 ⇒ `build*`)。
+ *
+ * 🔴 为什么 hash 而不是把 principal 直接当主键:①principal 是自由文本身份串,做主键会让**长度**与
+ * **排序规则**变成安全面(一个 191 字符的 principal 在 190 宽的列上被静默截断 ⇒ 两个身份共用一只桶,
+ * 那是一次跨租户放行);②`local-owner` 那一员**没有** principal,需要一个同域的定长表示。
+ * 种别前缀让两族键不可能相撞(`principal:` vs `local-owner`)。
+ */
+export declare function buildRuleOwnerKey(owner: RuleOwner): string;
+/** 内容三列 + 观测向量的完整性指纹(core `ruleStoreChecksum` 同精神;**不含** rev/counter —— 那两样
+ *  是元数据轴,`nextDot` 只动 counter 就不该迫使重算内容指纹)。
+ *
+ *  导出(纯数据 ⇒ `build*`)是为了让**取证测试**能造一条「指纹自洽但语义矛盾」的行 —— 那正是
+ *  codex round1 [high] 二的形:一条只靠指纹是拦不住的坏行,必须由语义筛拦。 */
+export declare function buildRuleBucketChecksum(body: {
+    rules: readonly unknown[];
+    tombstones: readonly unknown[];
+    quarantined: readonly unknown[];
+    observedVector?: RuleSyncFrontier;
+}): string;
+/**
+ * SQL 双方言的 {@link PermissionRuleStoreProvider}。
+ *
+ * `forPrincipal(undefined)` 恒解析成**零规则**店(core 硬条款:未鉴权任务解析到零规则而不是一只共享桶
+ * —— 放宽面上的 fail-closed 是「更少的允许」,绝不是「一只共享的」)。
+ */
+export declare class SqlPermissionRuleStoreProvider implements PermissionRuleStoreProvider {
+    private readonly db;
+    private readonly now;
+    constructor(db: SqlDriver, now?: () => number);
+    forPrincipal(principal: string | undefined): PermissionRuleStore;
+    forLocalOwner(): PermissionRuleStore;
+}
+export declare function createTiDBPermissionRuleStoreProvider(pool: MySqlPool, now?: () => number): SqlPermissionRuleStoreProvider;
+export declare function createPgPermissionRuleStoreProvider(pool: PgPool, now?: () => number): SqlPermissionRuleStoreProvider;
+/**
+ * durable 审批记录。CAS **按 rev**,不按 state —— core 的原话:批记录的第二个候选会 redeemed→redeemed,
+ * 只比 state 的两次并发重试会**都**认为自己看到了预期状态,各铸一个 dot、各写一次,后者静默覆盖前者的
+ * `redeemedDots`。那正是「一次同意变成两个 add、一条删掉的规则复活」的机制。
+ */
+export declare class SqlRuleApprovalRecordStore implements RuleApprovalRecordStore {
+    private readonly db;
+    private readonly now;
+    constructor(db: SqlDriver, now?: () => number);
+    private q;
+    private enc;
+    get(id: string): Promise<RuleApprovalRecord | undefined>;
+    create(record: RuleApprovalRecord): Promise<void>;
+    /**
+     * 丢弃一条**从未被确认**的记录(codex 交叉复审 round8 [medium],可控半场)。
+     *
+     * 用处只有一个:`prepareCcImport` 会在**返回预览之前**就把 pending 记录落盘,所以「预览超帽、这次导入
+     * 不做了」这条路会留下一条永远没人要的行。`WHERE state = 'pending'` 是硬的 —— 已确认/已兑付的记录是
+     * 一次真人同意的**审计事实**,任何路径都不许把它删掉(那条轴上的清理属于保留期策略,不是本方法)。
+     * 不是 core `RuleApprovalRecordStore` 的成员(那个接口只有 get/cas/create),故命名上与它区分。
+     */
+    discardPendingRecord(recordId: string): Promise<boolean>;
+    /** compare-and-set on `rev`(core 硬条款)。`next.rev` 必须是 `expectRev + 1`;不是 ⇒ 响亮拒绝
+     *  (一个不推进的 CAS 会让两次写互相覆盖而两边都以为自己赢了)。 */
+    cas(id: string, expectRev: number, next: RuleApprovalRecord): Promise<boolean>;
+}
+/** 一张已铸的票(呈给调用方的形;`payload` 是 prepare 时刻的候选快照)。 */
+export interface RuleImportTicket {
+    ticketId: string;
+    approvalId: string;
+    payloadHash: string;
+    expiresAtMs: number;
+}
+/** 消费结果。**四种拒绝合并成一个 `refused` 形**是刻意的:调用点把它们全部翻成同一个 404,
+ *  于是「这张票不存在」「它是别人的」「它过期了」「它已经用过了」在 wire 上不可区分(禁存在性 oracle)。 */
+export type RuleTicketRedeemResult = {
+    ok: true;
+    approvalId: string;
+    payloadHash: string;
+} | {
+    ok: false;
+    reason: "unknown" | "wrong-principal" | "expired" | "consumed";
+};
+/** prepare 时刻候选集的规范摘要(载荷绑定 F1 ④ 的判据)。纯数据 ⇒ `build*`。 */
+export declare function buildRulePayloadHash(candidates: ReadonlyArray<{
+    rule: string;
+    scope: RuleScope;
+}>): string;
+export declare class SqlRuleImportTicketStore {
+    private readonly db;
+    private readonly now;
+    constructor(db: SqlDriver, now?: () => number);
+    private q;
+    mint(input: {
+        ticketId: string;
+        principal: string;
+        approvalId: string;
+        candidates: ReadonlyArray<{
+            rule: string;
+            scope: RuleScope;
+        }>;
+        ttlMs: number;
+    }): Promise<RuleImportTicket>;
+    /**
+     * **一次性原子认领**(F1 ③)。四个条件全部写在 `WHERE` 里 —— ticket 身份、principal 绑定、未过期、
+     * 未认领 —— 于是并发双 redeem 由引擎的行锁裁决,恰一条 `affected === 1`。
+     *
+     * 🔴 **认领的 UPDATE 是这条方法的最后一次 I/O**(codex 交叉复审 round4 [high],验真后修)。
+     * 旧形是「先 UPDATE 认领、再 SELECT 取 approvalId/payloadHash」——那条 SELECT 失败时本方法**抛错**,
+     * 而调用方(`redeemImport`)此时还没进它的恢复 `try`,于是**没有任何人去放回认领**:票被永久烧掉,
+     * 重试收到不可重试的 404,人的确认凭空消失。改法不是加一层 catch,而是**把那次读挪到认领之前**:
+     * `approval_id` / `payload_hash` 自铸票起就是**不可变**列,先读与后读读到的是同一份字节。
+     *
+     * 🔴 **这仍然不是 read-then-write**(禁令的语义没有松动):**裁决**依旧只由那条条件 `UPDATE` 的
+     * `WHERE` 做出 —— 预读的三条否定项只用来**短路 + 归因**(把拒绝分成 unknown/wrong-principal/
+     * expired/consumed 四类给服务端日志;wire 面把四类折成同一个 404)。预读说「可以」而 UPDATE 命中零行,
+     * 只可能是我们在这两跳之间输给了一个并发认领者 —— 如实报 `consumed`,而不是把这次失败当成成功。
+     */
+    consume(ticketId: string, principal: string): Promise<RuleTicketRedeemResult>;
+    /**
+     * **认领的释放**(codex 交叉复审 round1 [high] 一,验真后修)。
+     *
+     * `consume` 是一次**认领**(claim),不是「这件事已经做完了」。认领之后还有三步会失败:读记录、
+     * 载荷比对、confirm+批量兑付。旧形把认领当终局 ⇒ 一次数据库抖动就让票**永久**烧掉,而调用方拿到的
+     * 是与「票不存在」同形的 404:重试无门、最终状态对客户端不可判。
+     *
+     * ⇒ 认领之后**只有裁定性拒绝**才留着消费位(载荷被篡改、记录不存在 —— 重试不改判);**不确定/瞬时**
+     * 的失败(store 抛错、CAS 冲突)把认领**放回去**,让属主重试。放回去不会打开双兑付的门:同一时刻
+     * 只有一个持有者(认领本身仍是单条条件 UPDATE),而兑付腿(`redeemRuleBatch`)按 core 的设计是
+     * **幂等**的(记录里存着每个候选已铸的 dot,重放只会重放同一个 dot)。
+     *
+     * 残留(如实登记,不假称已解):认领与释放之间**硬崩**会把票留在已认领态 —— 它随 TTL 自然消失,
+     * 期间属主可以重新走 prepare 拿一张新票(导入是幂等的:同一条规则再兑付只是同一个 dot 的重放)。
+     * 要彻底消灭它需要一条带租约到期的认领状态机,属协议改动,列为后续件。
+     */
+    release(ticketId: string, principal: string, mustRemainValidMs?: number): Promise<boolean>;
+    private readRow;
+}
+/** 三个 SQL 店的一次性装配束(one driver, three faces)。 */
+export interface PermissionRuleStores {
+    provider: SqlPermissionRuleStoreProvider;
+    approvals: SqlRuleApprovalRecordStore;
+    tickets: SqlRuleImportTicketStore;
+    /** #203 §3 —— boot 期休眠行审计的**窄读口**:库里已有几只桶(`permission_rule` 一行一桶)。
+     *
+     *  🔴 为什么数**桶**而不是数**规则**:数规则要把每一行的 `rules_json` 都读回来再解析(一只桶的规则集
+     *  没有硬上限,顶注 §列宽依据已说明它是 LONGTEXT),那是一次无界的 boot 期扫描 —— 为一条诊断行付这个
+     *  代价不划算。桶数回答的正是审计要问的那个问题(「这台部署上有没有既有的规则状态」),而且是一次
+     *  索引级 `COUNT(*)`。消费点(`boot/permission-rules-audit.ts`)的文案因此逐字说的是 bucket,不是 rule。 */
+    countBuckets(): Promise<number>;
+}
+export declare function createSqlPermissionRuleStores(db: SqlDriver, now?: () => number): PermissionRuleStores;
+//# sourceMappingURL=permission-rule-store-sql.d.ts.map