@agent-native/core 0.201.1 → 0.202.0-nightly-20261006033736

package/dist/sharing/access-request-store.js

@@ -0,0 +1,213 @@
+import { randomBytes } from "node:crypto";
+import { getDbExec } from "../db/client.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
+const TABLE = "resource_access_requests";
+let _initPromise;
+export async function ensureTable() {
+    if (!_initPromise) {
+        _initPromise = (async () => {
+            await ensureTableExists(TABLE, `CREATE TABLE IF NOT EXISTS ${TABLE} (
+          id TEXT PRIMARY KEY,
+          resource_type TEXT NOT NULL,
+          resource_id TEXT NOT NULL,
+          requester_email TEXT NOT NULL,
+          requester_name TEXT,
+          owner_email TEXT NOT NULL,
+          note TEXT,
+          state TEXT NOT NULL,
+          generation INTEGER NOT NULL DEFAULT 1,
+          requested_at BIGINT NOT NULL,
+          created_at BIGINT NOT NULL,
+          decided_by TEXT,
+          decided_at BIGINT,
+          granted_role TEXT,
+          delivery TEXT
+        )`);
+            await ensureIndexExists("idx_resource_access_requests_requester", `CREATE UNIQUE INDEX IF NOT EXISTS idx_resource_access_requests_requester ON ${TABLE} (resource_type, resource_id, requester_email)`);
+            await ensureIndexExists("idx_resource_access_requests_requester_recent", `CREATE INDEX IF NOT EXISTS idx_resource_access_requests_requester_recent ON ${TABLE} (requester_email, requested_at)`);
+            await ensureIndexExists("idx_resource_access_requests_owner_recent", `CREATE INDEX IF NOT EXISTS idx_resource_access_requests_owner_recent ON ${TABLE} (owner_email, requested_at)`);
+        })().catch((err) => {
+            _initPromise = undefined;
+            throw err;
+        });
+    }
+    return _initPromise;
+}
+function optionalString(value) {
+    return value == null ? null : String(value);
+}
+function optionalNumber(value) {
+    return value == null ? null : Number(value);
+}
+function parseRow(row) {
+    return {
+        id: String(row.id),
+        resourceType: String(row.resource_type),
+        resourceId: String(row.resource_id),
+        requesterEmail: String(row.requester_email),
+        requesterName: optionalString(row.requester_name),
+        ownerEmail: String(row.owner_email),
+        note: optionalString(row.note),
+        state: String(row.state),
+        generation: Number(row.generation),
+        requestedAt: Number(row.requested_at),
+        createdAt: Number(row.created_at),
+        decidedBy: optionalString(row.decided_by),
+        decidedAt: optionalNumber(row.decided_at),
+        grantedRole: optionalString(row.granted_role),
+        delivered: row.delivery != null,
+    };
+}
+function newRequestId() {
+    return randomBytes(12).toString("base64url");
+}
+export async function getAccessRequest(id) {
+    await ensureTable();
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT * FROM ${TABLE} WHERE id = ? LIMIT 1`,
+        args: [id],
+    });
+    return rows[0] ? parseRow(rows[0]) : null;
+}
+export async function findAccessRequest(resourceType, resourceId, requesterEmail) {
+    await ensureTable();
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT * FROM ${TABLE} WHERE resource_type = ? AND resource_id = ? AND requester_email = ? LIMIT 1`,
+        args: [resourceType, resourceId, requesterEmail],
+    });
+    return rows[0] ? parseRow(rows[0]) : null;
+}
+export async function listPendingAccessRequests(resourceType, resourceId, limit) {
+    await ensureTable();
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT * FROM ${TABLE} WHERE resource_type = ? AND resource_id = ? AND state = 'pending' ORDER BY requested_at DESC LIMIT ?`,
+        args: [resourceType, resourceId, limit],
+    });
+    return rows.map(parseRow);
+}
+/**
+ * How many requests were asked since `since` by one requester or against one
+ * owner, and when the oldest of them was asked.
+ */
+export async function countRecentAccessRequests(by, since) {
+    await ensureTable();
+    const [column, value] = "requesterEmail" in by
+        ? ["requester_email", by.requesterEmail]
+        : ["owner_email", by.ownerEmail];
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT COUNT(*) AS n, MIN(requested_at) AS oldest FROM ${TABLE} WHERE ${column} = ? AND requested_at > ?`,
+        args: [value, since],
+    });
+    return {
+        count: Number(rows[0]?.n ?? 0),
+        oldestAt: optionalNumber(rows[0]?.oldest),
+    };
+}
+/**
+ * Opens a request, or reopens a closed one as a new generation. A pending
+ * request whose send was cut off before anyone was told is claimed again in
+ * its own generation, so recipients the cut-off send reached get nothing new.
+ * Returns `opened: false` with the existing row when a request is already
+ * pending, or was declined too recently to ask again, so the caller sends
+ * nothing.
+ */
+export async function openAccessRequest(input) {
+    await ensureTable();
+    const { rows } = await getDbExec().execute({
+        sql: `INSERT INTO ${TABLE} (
+        id, resource_type, resource_id, requester_email, requester_name,
+        owner_email, note, state, generation, requested_at, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', 1, ?, ?)
+      ON CONFLICT (resource_type, resource_id, requester_email) DO UPDATE SET
+        requester_name = excluded.requester_name,
+        owner_email = excluded.owner_email,
+        note = excluded.note,
+        state = 'pending',
+        generation = ${TABLE}.generation + 1,
+        requested_at = excluded.requested_at,
+        decided_by = NULL,
+        decided_at = NULL,
+        granted_role = NULL,
+        delivery = NULL
+      WHERE ${TABLE}.state = 'approved'
+        OR (${TABLE}.state = 'declined' AND ${TABLE}.decided_at <= ?)
+      RETURNING *`,
+        args: [
+            newRequestId(),
+            input.resourceType,
+            input.resourceId,
+            input.requesterEmail,
+            input.requesterName,
+            input.ownerEmail,
+            input.note,
+            input.now,
+            input.now,
+            input.declinedCooldownStart,
+        ],
+    });
+    if (rows[0])
+        return { request: parseRow(rows[0]), opened: true };
+    // Moving requested_at makes the claim one ask's alone.
+    const { rows: unsent } = await getDbExec().execute({
+        sql: `UPDATE ${TABLE} SET requested_at = ?
+      WHERE resource_type = ? AND resource_id = ? AND requester_email = ?
+        AND state = 'pending' AND delivery IS NULL AND requested_at <= ?
+      RETURNING *`,
+        args: [
+            input.now,
+            input.resourceType,
+            input.resourceId,
+            input.requesterEmail,
+            input.sendWindowStart,
+        ],
+    });
+    if (unsent[0])
+        return { request: parseRow(unsent[0]), opened: true };
+    const existing = await findAccessRequest(input.resourceType, input.resourceId, input.requesterEmail);
+    if (!existing)
+        throw new Error("Access request conflict could not be read.");
+    return { request: existing, opened: false };
+}
+/**
+ * Withdraws a request that was just opened but reached nobody, so asking
+ * again isn't blocked and doesn't count toward the limits. Only the ask that
+ * opened or claimed it at `requestedAt` can: one another ask has claimed
+ * since, or already delivered, stays.
+ */
+export async function deleteAccessRequest(id, generation, requestedAt) {
+    await ensureTable();
+    await getDbExec().execute({
+        sql: `DELETE FROM ${TABLE} WHERE id = ? AND generation = ? AND requested_at = ? AND state = 'pending' AND delivery IS NULL`,
+        args: [id, generation, requestedAt],
+    });
+}
+export async function recordAccessRequestDelivery(id, generation, delivery) {
+    await ensureTable();
+    await getDbExec().execute({
+        sql: `UPDATE ${TABLE} SET delivery = ? WHERE id = ? AND generation = ?`,
+        args: [JSON.stringify(delivery), id, generation],
+    });
+}
+/**
+ * Closes a pending request. Only a request still pending in the generation
+ * the decider saw changes, so a decision on a stale page can't close a newer
+ * ask and two people can't both decide one. Pass the transaction a grant runs
+ * in so both commit together.
+ */
+export async function decideAccessRequest(input, exec = getDbExec()) {
+    await ensureTable();
+    const { rows } = await exec.execute({
+        sql: `UPDATE ${TABLE} SET state = ?, decided_by = ?, decided_at = ?, granted_role = ?
+      WHERE id = ? AND generation = ? AND state = 'pending'
+      RETURNING *`,
+        args: [
+            input.state,
+            input.decidedBy,
+            input.now,
+            input.grantedRole,
+            input.id,
+            input.generation,
+        ],
+    });
+    return rows[0] ? parseRow(rows[0]) : null;
+}

package/dist/sharing/access-requests.d.ts

@@ -0,0 +1,113 @@
+import { type AccessRequestRow } from "./access-request-store.js";
+import { type ResourceAccessStatus } from "./access.js";
+import type { ShareRole } from "./schema.js";
+export declare const ACCESS_REQUEST_NOTE_MAX_LENGTH = 500;
+/** How long a declined requester waits before they can ask again. */
+export declare const ACCESS_REQUEST_DECLINE_COOLDOWN_MS: number;
+/** Requests one person can make in a day, across every resource. */
+export declare const ACCESS_REQUESTS_PER_REQUESTER_PER_DAY = 20;
+/** Requests one owner can receive in a day, across their resources. */
+export declare const ACCESS_REQUESTS_PER_OWNER_PER_DAY = 50;
+/**
+ * How long a request nobody has been told about yet reads as still sending.
+ * After that its send was cut off, and asking again sends it again; the
+ * request's idempotency keys stop anyone it already reached hearing twice.
+ */
+export declare const ACCESS_REQUEST_SEND_WINDOW_MS: number;
+/** Where someone who manages access reviews a request, relative to the app. */
+export declare function accessRequestReviewPath(requestId: string): string;
+/** The viewer's own request, as their access screen shows it. */
+export interface ViewerAccessRequest {
+    state: "pending";
+    requestedAt: string;
+}
+export interface ResourceLinkStatus extends ResourceAccessStatus {
+    /** Whether the viewer can ask for access now. Only for `denied`. */
+    canRequest?: boolean;
+    /** The viewer's open request, if any. Only for `denied`. */
+    request?: ViewerAccessRequest;
+}
+/**
+ * {@link resolveAccessStatus}, plus whether a viewer who can't open the
+ * resource can ask for access, and their own open request if they already
+ * asked. Registrations without `accessRequests` never offer it.
+ */
+export declare function resolveLinkStatus(resourceType: string, resourceId: string): Promise<ResourceLinkStatus>;
+export type RequestResourceAccessResult = {
+    state: "allowed";
+} | {
+    state: "requested";
+    request: ViewerAccessRequest;
+    sent: boolean;
+};
+/**
+ * Asks the owner, and anyone with admin, to give the signed-in viewer access
+ * to a resource they can't open. Asking again while a request is open sends
+ * nothing; asking again after its send was cut off sends it again. If the
+ * request is over a daily limit, or nobody could be told, it is withdrawn
+ * and this fails, so the viewer never sees "sent" for a request nobody will
+ * find.
+ */
+export declare function requestResourceAccess(input: {
+    resourceType: string;
+    resourceId: string;
+    note?: string;
+}): Promise<RequestResourceAccessResult>;
+export interface AccessRequestReview {
+    id: string;
+    generation: number;
+    state: AccessRequestRow["state"];
+    requester: {
+        email: string;
+        name: string | null;
+    };
+    note: string | null;
+    requestedAt: string;
+    decidedAt: string | null;
+    grantedRole: ShareRole | null;
+    resource: {
+        type: string;
+        id: string;
+        label: string;
+        title: string;
+        path: string | null;
+    };
+}
+/** A request, for someone who manages access to its resource. */
+export declare function getAccessRequestReview(requestId: string): Promise<AccessRequestReview>;
+export interface ResourceAccessRequestList {
+    /** The newest pending requests. */
+    requests: AccessRequestReview[];
+    /** Older pending requests exist beyond `requests`. */
+    hasMore: boolean;
+}
+/** Pending requests for one resource, for someone who manages its access. */
+export declare function listResourceAccessRequests(resourceType: string, resourceId: string): Promise<ResourceAccessRequestList>;
+/**
+ * Whether the requester was emailed that they're in: `skipped` when the app
+ * has no email set up or the requester is a test identity, `failed` when
+ * sending failed or the email setup is broken or unreadable.
+ */
+export type AccessGrantedEmail = "sent" | "skipped" | "failed";
+/**
+ * Gives the requester `role`, through the same grant and sharing rules as
+ * Share, and closes the request in the same transaction. A stronger role the
+ * requester already holds is kept. The access stands even when the email
+ * telling them fails; `email` says so.
+ */
+export declare function approveAccessRequest(input: {
+    requestId: string;
+    generation: number;
+    role: ShareRole;
+}): Promise<{
+    state: "approved";
+    role: ShareRole;
+    email: AccessGrantedEmail;
+}>;
+/** Closes a request without granting anything or telling the requester. */
+export declare function declineAccessRequest(input: {
+    requestId: string;
+    generation: number;
+}): Promise<{
+    state: "declined";
+}>;