tapline-host 1.6.2 → 1.7.0

package/dist/grants.d.ts

@@ -0,0 +1,297 @@
+import type { AuditSink } from "./auditlog.js";
+import { type PidLockDeps } from "./pidlock.js";
+/**
+ * AGENT-TOOLS 1.14 §19: grants. A person's standing OK for a kind of touch, with limits, given ahead of time. A grant lives
+ * in the policy file (version 2), is counted as slot files under `<policy file>.uses/` (no lock, no state file), and every use is a
+ * line of the audit log (§23). Only a person makes a grant; nothing here creates, edits or lifts one.
+ */
+/** The most days away a grant's `until` may be, counted from the day the file is loaded (§19.1). */
+export declare const GRANT_MAX_DAYS = 30;
+export interface Grant {
+    name: string;
+    /** The app's id (or, when it has none, its name). */
+    app: string;
+    words: string[];
+    route?: string;
+    perDay: number;
+    perHour?: number;
+    /** A local date, `YYYY-MM-DD`: the grant covers touches up to the end of that day. */
+    until: string;
+    quiet?: {
+        from: string;
+        to: string;
+    };
+    /** The effective value (§19.1): absent in the file, it is true for a word that reaches other people. */
+    draftsOnly: boolean;
+    /** A local date: the day a person or `--revoke-all` revoked it. */
+    revoked?: string;
+}
+export interface GrantRefusal {
+    /** The grant's name, or `#3` (its place in the list) when it has none. */
+    name: string;
+    /** The reason, a sentence ending in a full stop. */
+    reason: string;
+}
+/** The note a refused grant gets (§19.1). */
+export declare const refusalLine: (refusal: GrantRefusal) => string;
+/** Words the tool treats as a payment or a purchase. */
+export declare const PAYMENT_WORDS: string[];
+/** Words that delete an account. (Privacy and security settings and Wallet are recognised by screen: Tapwright's to enforce.) */
+export declare const ACCOUNT_WORDS: string[];
+/** Words that reach other people: a grant that names one is draftsOnly unless a person lifted it (§19.1, §21.3). */
+export declare const REACH_WORDS: string[];
+/** Why a word can never be granted, or null. `block` is the policy's block list for the grant's app. */
+export declare function neverReason(word: string, block: string[]): string | null;
+/** The local calendar day, `YYYY-MM-DD`. */
+export declare function localDate(d: Date): string;
+/** ISO 8601 in local time with its offset, as a slot file keeps it (§19.4). */
+export declare function localIso(d: Date): string;
+/**
+ * Reads a policy file's `grants`. A grant that is invalid, longer than 30 days or never grantable is refused alone: the
+ * others load, and the reason is kept (§19.1). `today` is the local day the file is loaded; `block` is the policy's block list for an app.
+ */
+export declare function parseGrants(raw: unknown, today: string, block: (app: string) => string[]): {
+    grants: Grant[];
+    refused: GrantRefusal[];
+};
+/** What two grant names are compared by: equal ignoring ASCII case (names are limited to `[A-Za-z0-9._-]`). Names that agree here are one name. */
+export declare function grantKey(name: string): string;
+/**
+ * The folder a grant's uses live in: its name lower-cased (a safe name is ASCII only, so this is exactly its case-folded form). A
+ * name's case therefore never picks another folder, and `g` and `G` are one folder on every file system.
+ */
+export declare function usesFolder(name: string): string;
+/** The policy file's edit lock (§19.5). */
+export declare function policyEditLockPath(policyPath: string): string;
+/** Whether a grant's name is safe as a folder name: letters, digits, `_`, `.` and `-`; never `.`, `..` or one that ends in a dot (Windows drops it). */
+export declare function safeGrantName(name: string): boolean;
+/** What a touch is, for a grant to match: the app, the element's own label and text, and the saved routes running now. */
+export interface GrantTouch {
+    app: {
+        id?: string;
+        name: string;
+    };
+    element: {
+        label?: string | null;
+        text?: string | null;
+    };
+    routes: string[];
+}
+/** What `release` and `stillCovers` need to know of a use: who made it and which slot files (relative to the uses folder, `/`-separated) hold it. */
+export interface GrantUseRef {
+    name: string;
+    owner: string;
+    slots: string[];
+}
+export type GrantDecision = 
+/** `owner` and `slots` name the recorded use, so `release` can take it back when the touch wasn't made (`peek` has none). */
+{
+    kind: "covered";
+    name: string;
+    line: string; /** `2 of 3`, for a dry run's words. */
+    counts: string;
+    counted: boolean;
+    owner: string;
+    slots: string[];
+}
+/**
+ * A draftsOnly grant covers the touch (§19.3): the touch stops before it is made and shows a draft to a person (§21.3). Nothing is
+ * counted: a draft a person sends isn't a use of the grant, the person's OK let it through.
+ */
+ | {
+    kind: "draft";
+    name: string;
+}
+/** The touch asks a person; `notes` say why a grant that matched didn't cover it (§19.3). */
+ | {
+    kind: "ask";
+    notes: string[]; /** Why each matching grant didn't cover it, in the report's words: `limit reached`, `quiet hours`, `ended`, `revoked`. */
+    asked: string[];
+};
+/** What a look at the policy file and the uses folder found, for `doctor` and the first answer (§19.1, §19.4). */
+export interface GrantReport {
+    /** False when the policy file can't be read or parsed any more: no grant covers anything. */
+    fileOk: boolean;
+    grants: Grant[];
+    refused: GrantRefusal[];
+    /** The uses folder (or a grant's folder in it) can't be read: that grant counts as used up. */
+    usesBroken: boolean;
+}
+export interface GrantBookOptions {
+    policyPath: string;
+    /** The audit log. Without one no grant covers a touch: a grant needs its line (§23). */
+    audit: AuditSink | null;
+    /** The clock. A claim reads it again when it claims, so the day and the hour it counts against are the ones it claims in. */
+    now?: () => Date;
+    /** For tests: runs before each exclusive create of a slot file (a writer that pauses at any point). */
+    beforeCreate?: (path: string) => Promise<void>;
+    /** For tests: runs after a use's slot files exist and before the policy is read again and the audit line written. */
+    afterClaim?: () => Promise<void>;
+    /** For tests: runs in `stillCovers` after the use's slot files were read and before the clock is read for the final check. */
+    afterSlotReads?: () => Promise<void>;
+    /** For tests: runs inside the edit lock, after the policy was read and checked and before the new file is written. */
+    beforePolicyWrite?: () => Promise<void>;
+    /** The process facts the policy file's edit lock uses (pid, liveness, start time). Default: this process. */
+    editLock?: PidLockDeps;
+    /** How long a change waits for the edit lock before it gives up and changes nothing. Default 5000 ms. */
+    editLockWaitMs?: number;
+    /** How often a change that waits for the edit lock tries again. Default 25 ms. */
+    editLockPollMs?: number;
+}
+export declare class GrantBook {
+    private readonly options;
+    private readonly now;
+    private readonly usesRoot;
+    constructor(options: GrantBookOptions);
+    get policyPath(): string;
+    /** The policy file read again, on every call: a revocation by hand or by the other tool is seen at the next touch (§19.5). */
+    private readPolicy;
+    /** The uses of a grant in the day and the hour of `at`, by listing the folders; null when one can't be read (fails closed). */
+    private countsAt;
+    /** Every grant, what was refused, and whether a uses folder can't be read: for `doctor` and the session's first answer. */
+    inspect(): Promise<GrantReport>;
+    /** The date, `YYYY-MM-DD`, that is `days` from today (at most 30), for the dialog's question and a new grant's `until`. */
+    untilFor(days: number): string;
+    /** Every grant with today's and this hour's counts (null when its uses can't be read), for `tapline grants` (§19.7). */
+    listing(): Promise<{
+        report: GrantReport;
+        usage: Map<string, {
+            today: number;
+            hour: number;
+        } | null>;
+    }>;
+    /**
+     * Prune (at start, §19.4): the uses of a grant that has ended (today is after its `until`) or was revoked are deleted. Nothing else
+     * is ever counted from an earlier day or hour, so nothing else is needed. Returns the names it cleared.
+     */
+    prune(): Promise<string[]>;
+    /** Deletes a grant's whole uses folder; false for a name that isn't safe as a folder name or when it can't be deleted. */
+    private removeUses;
+    /**
+     * `grants --revoke-all` (§19.5): marks every grant in the policy file `"revoked": "<today>"` and writes one `revoke` audit
+     * line each, and deletes the revoked grants' uses. A grant that is already revoked keeps its date. The file is changed with a
+     * temporary file and a rename, and every running tool sees it at its very next touch, because each touch reads the file again.
+     */
+    revokeAll(detail?: string): Promise<{
+        revoked: string[];
+        already: string[];
+    } | {
+        error: string;
+    }>;
+    /**
+     * Writes a grant a person made through the dialog (§19.6) into the policy file: a temporary file and a rename, a name not used
+     * yet, `until` at most 30 days away, a version 1 file becoming version 2. The creation is logged (§23, `approval`). Only the
+     * host's dialog calls this, with what the person answered; nothing a model sends reaches it.
+     */
+    create(spec: GrantSpec): Promise<{
+        grant: Grant;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Every change to the policy file (create, renew, lifting draftsOnly, revoke-all) runs under `<policy file>.edit.lock`: the shared
+     * pid-liveness lock (pidlock.ts), which no one can displace while its holder lives. Under it the file is read again and the change is
+     * applied to that fresh content, never to an earlier copy; the result is written with a temporary file and a rename. A change that
+     * can't get the lock within `editLockWaitMs` fails closed: nothing is written. A string is why it couldn't.
+     */
+    private editPolicy;
+    /** The change itself, run under the edit lock: reads the file as it is now, lets `change` edit it, writes it back when it says it did. */
+    private editPolicyLocked;
+    /** The `Note:` lines of an inspection: each refused grant, and a uses folder that can't be read. */
+    static noticeLines(report: GrantReport): string[];
+    /**
+     * Whether a grant covers this touch (§19.3). Called where the host has decided the touch needs a person: a covered touch goes
+     * through, and anything else asks as before, with the notes. `use` claims the use's slot files and writes the audit line;
+     * `peek` claims and writes nothing (a dry run, and the check before a dialog). `detail` is what the audit line says.
+     */
+    decide(touch: GrantTouch, mode: "use" | "peek", detail: string): Promise<GrantDecision>;
+    /**
+     * Whether the grant a use was taken under still covers this touch, right now (§19.3): the policy file is read again, and the clock
+     * too, so a revocation, a `draftsOnly`, quiet hours, `until`, the word and the route condition are current. Takes no use and writes
+     * nothing; the use's slot files must all still be there and still be this use's. Any doubt (an unreadable file) answers false: the
+     * touch then asks a person.
+     */
+    stillCovers(touch: GrantTouch, use: GrantUseRef): Promise<boolean>;
+    /**
+     * Whether a claim still fits the grant as the policy file has it now: its day slot number is within perDay, and, when the grant has a
+     * perHour, it holds an hour slot whose number is within perHour. A policy that was changed between the claim and the touch (a quota
+     * cut, a perHour added) makes an old claim fall outside the new limits; it is then given back and claimed again, or the touch asks.
+     */
+    private fits;
+    /**
+     * Under the grant as it is now, the whole bucket (every entry of the day folder, and of the hour folder with a perHour; garbage counts
+     * as section 19.4 says) must hold at most the limit, this use's own slot included. "" means within the limits; otherwise the limit
+     * that is exceeded in words; null, a bucket that can't be read (any doubt asks a person).
+     */
+    private overLimit;
+    /** Whether every slot of a use is in the day (or hour) folder of `at`: a use from an earlier day or hour is not counted against the current one. */
+    private inCurrentBuckets;
+    /** Whether this grant, as the policy file has it now, covers the touch at this time: app, word, route, revocation, end, quiet hours, drafts. */
+    private holds;
+    /** The absolute path of a slot a use names, or null when it isn't a slot of that grant (never a path outside the uses folder). */
+    private slotPath;
+    /** A use taken back: the touch wasn't made after all (§19.4: a use is counted when the touch is made). Deletes only this use's own slot files. */
+    release(use: GrantUseRef): Promise<void>;
+    /** Deletes the slot files of a use, each only after its content says this owner made it. A file that can't be read or deleted stays: the use stays counted. */
+    private dropSlots;
+    /** The limit that stops a use as words for the note, or null when there is room. */
+    private limit;
+    /** A string: the limit that stopped it. null: it can't be counted (an unreadable uses folder), nothing to say. */
+    private peek;
+    /**
+     * Claims a slot file in `dir` (k = 1..limit, exclusive create, the folder made as needed): the first k nobody has taken. A full
+     * folder answers how many entries it holds; a folder that can't be read or written answers null. Every entry counts, so a garbage
+     * file takes a place: a folder holding more entries than `limit` after the claim gives the claim back.
+     */
+    private claimSlot;
+    /**
+     * Claims the slot files of one use in the buckets of a fresh clock: the hour slot first (when there is a perHour), then the day slot;
+     * a day claim that fails gives the hour slot back. The clock is read again after the claim: when the day (or the hour, with a perHour)
+     * moved on meanwhile, the slots just made are in an earlier bucket, so they are deleted and the claim is made again in the current
+     * one (a claimer that paused across midnight never counts against yesterday). A string is the limit that stopped it; null, that it
+     * can't be counted.
+     */
+    private claimBuckets;
+    /**
+     * Claims a use (see claimBuckets), then the policy and the clock are read again (a revocation, an end or quiet hours that came
+     * meanwhile win) and the audit line is written; a grant needs its line, so a use whose line can't be written is given back (§23).
+     * A string is the limit that stopped it; null, that it can't be counted.
+     */
+    private use;
+    /** A temporary file and a rename, with retries on Windows. */
+    private writeAtomic;
+}
+/** What the person said yes to in the dialog (§19.6). `days` counts from today, at most 30. */
+export interface GrantSpec {
+    /** A name to start from; a number is added when it is taken. */
+    nameBase: string;
+    app: string;
+    words: string[];
+    route?: string;
+    perDay: number;
+    perHour?: number;
+    days: number;
+    quiet?: {
+        from: string;
+        to: string;
+    };
+    /** Only `false` is written (the person said Yes to sending without drafts); otherwise the file says nothing (§19.1). */
+    draftsOnly?: false;
+}
+/** Whether the element touched is a payment or an account deletion: no grant covers it, whatever its word (§19.2). */
+export declare const elementNeverGrantable: (element: {
+    label?: string | null;
+    text?: string | null;
+}) => boolean;
+/** Whether a word reaches other people, so a grant for it shows drafts first unless a person lifts that (§19.1). */
+export declare const reachesPeople: (word: string) => boolean;
+/**
+ * The dialog's question, saying everything the grant allows (§19.6):
+ * `Allow tapping "Post" in Instagram up to 3 times a day, only in route post_update, until 21 Nov (drafts shown to you first)?`
+ * `app` is the app's name as the dialog may show it (already cut and cleaned); words are cleaned here.
+ */
+export declare function grantCaption(grant: Pick<Grant, "words" | "perDay" | "perHour" | "until" | "route" | "quiet" | "draftsOnly">, app: string): string;
+/** A grant's name from the app's name and the word, as `instagram_post`: ASCII letters, digits and `_`. */
+export declare function grantNameBase(app: string, word: string): string;
+/** Whether a whole-word match for a word is a payment or an account deletion: never grantable, so never offered (§19.2). */
+export declare const neverGrantable: (word: string, block: string[]) => boolean;