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

package/dist/sharing/access-requests.js

@@ -0,0 +1,490 @@
+import { and, asc, eq } from "drizzle-orm";
+import { fail } from "../action.js";
+import { getDbExec, withDbExec } from "../db/client.js";
+import { CORE_ACCESS_GRANTED_EMAIL_ID, CORE_ACCESS_REQUESTED_EMAIL_ID, renderTransactionalEmail, } from "../email-catalog/templates.js";
+import { notifyWithDelivery } from "../notifications/registry.js";
+import { getAppProductionUrl } from "../server/app-url.js";
+import { resolveEmailBrandApp } from "../server/email-templates.js";
+import { getEmailReadiness, isEmailConfigured, sendEmail, } from "../server/email.js";
+import { getUserProfile } from "../user-profile/store.js";
+import { decideAccessRequest, deleteAccessRequest, findAccessRequest, getAccessRequest, listPendingAccessRequests, countRecentAccessRequests, openAccessRequest, recordAccessRequestDelivery, } from "./access-request-store.js";
+import { currentAccess, resolveAccess, resolveAccessStatus, } from "./access.js";
+import { resolveShareNotificationUrl } from "./actions/share-resource.js";
+import { announceResourceAccessChange, grantResourceAccess } from "./grant.js";
+import { filterRecipientsByResourceAccess } from "./recipients.js";
+import { requireShareableResource, } from "./registry.js";
+export const ACCESS_REQUEST_NOTE_MAX_LENGTH = 500;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** How long a declined requester waits before they can ask again. */
+export const ACCESS_REQUEST_DECLINE_COOLDOWN_MS = 7 * DAY_MS;
+/** Requests one person can make in a day, across every resource. */
+export const ACCESS_REQUESTS_PER_REQUESTER_PER_DAY = 20;
+/** Requests one owner can receive in a day, across their resources. */
+export 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 const ACCESS_REQUEST_SEND_WINDOW_MS = 2 * 60 * 1000;
+// People shared directly as admin who hear about a request, besides the owner.
+const ADMIN_RECIPIENT_LIMIT = 20;
+const PENDING_LIST_LIMIT = 50;
+/** Where someone who manages access reviews a request, relative to the app. */
+export function accessRequestReviewPath(requestId) {
+    return `/access-requests/${encodeURIComponent(requestId)}`;
+}
+function iso(ms) {
+    return new Date(ms).toISOString();
+}
+function viewerEmail() {
+    return currentAccess().userEmail?.trim().toLowerCase() || null;
+}
+// A declined request reads to the requester as still pending until the
+// cooldown ends, so declining tells them nothing and they can't ask again
+// straight away. A pending one whose send was cut off before anyone was told
+// isn't open, so the requester isn't left waiting on nobody.
+function openRequestFor(row, now) {
+    if (!row)
+        return undefined;
+    const open = (row.state === "pending" &&
+        (row.delivered ||
+            row.requestedAt > now - ACCESS_REQUEST_SEND_WINDOW_MS)) ||
+        (row.state === "declined" &&
+            row.decidedAt !== null &&
+            row.decidedAt > now - ACCESS_REQUEST_DECLINE_COOLDOWN_MS);
+    return open
+        ? { state: "pending", requestedAt: iso(row.requestedAt) }
+        : undefined;
+}
+/**
+ * {@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 async function resolveLinkStatus(resourceType, resourceId) {
+    const status = await resolveAccessStatus(resourceType, resourceId);
+    const reg = requireShareableResource(resourceType);
+    const email = viewerEmail();
+    if (status.state !== "denied" || !reg.accessRequests || !email) {
+        return status;
+    }
+    const request = openRequestFor(await findAccessRequest(resourceType, resourceId, email), Date.now());
+    return request
+        ? { ...status, canRequest: false, request }
+        : { ...status, canRequest: true };
+}
+function requireSignedIn(message) {
+    const email = viewerEmail();
+    if (!email)
+        fail(message, { errorCode: "sign_in_required", statusCode: 401 });
+    return email;
+}
+async function loadResource(reg, resourceId) {
+    const [resource] = await reg.getDb()
+        .select()
+        .from(reg.resourceTable)
+        .where(eq(reg.resourceTable.id, resourceId));
+    return resource;
+}
+function resourceTitle(reg, resource) {
+    const title = resource?.[reg.titleColumn ?? "title"];
+    return typeof title === "string" && title.trim()
+        ? title.trim()
+        : reg.displayName;
+}
+function resourcePath(reg, resource) {
+    return reg.getResourcePath ? reg.getResourcePath(resource) : undefined;
+}
+async function emailBrand(reg, resource) {
+    const app = resolveEmailBrandApp();
+    let name = app.name;
+    let logoUrl = app.logoUrl;
+    try {
+        name = (await reg.getBrandName?.(resource))?.trim() || name;
+    }
+    catch (err) {
+        console.error("[access-requests] brand name resolver failed:", err);
+    }
+    try {
+        logoUrl = (await reg.getLogoUrl?.(resource)) ?? logoUrl;
+    }
+    catch (err) {
+        console.error("[access-requests] brand logo resolver failed:", err);
+    }
+    return { name, logoUrl };
+}
+// The owner and people shared directly as admin, kept only while their access
+// still resolves to admin: on a restricted resource an admin share grants
+// nothing outside its organization, and a request carries the title and the
+// note. Anyone who manages access another way, through an organization, a
+// group, or the app's own rule, sees requests in the Share panel instead.
+async function requestRecipients(reg, resource, request) {
+    const rows = await reg.getDb()
+        .select({ principalId: reg.sharesTable.principalId })
+        .from(reg.sharesTable)
+        .where(and(eq(reg.sharesTable.resourceId, request.resourceId), eq(reg.sharesTable.principalType, "user"), eq(reg.sharesTable.role, "admin")))
+        .orderBy(asc(reg.sharesTable.createdAt))
+        .limit(ADMIN_RECIPIENT_LIMIT);
+    const candidates = Array.from(new Set([
+        request.ownerEmail,
+        ...rows.map((row) => row.principalId.trim().toLowerCase()),
+    ])).filter((email) => email && email !== request.requesterEmail);
+    return filterRecipientsByResourceAccess({
+        resourceType: request.resourceType,
+        resourceId: request.resourceId,
+        emails: candidates,
+        orgId: resource.orgId,
+        minimumRole: "admin",
+    });
+}
+async function enforceRequestLimits(requesterEmail, ownerEmail, now) {
+    const since = now - DAY_MS;
+    for (const [by, limit] of [
+        [{ requesterEmail }, ACCESS_REQUESTS_PER_REQUESTER_PER_DAY],
+        [{ ownerEmail }, ACCESS_REQUESTS_PER_OWNER_PER_DAY],
+    ]) {
+        const recent = await countRecentAccessRequests(by, since);
+        if (recent.count <= limit)
+            continue;
+        const retryAt = iso((recent.oldestAt ?? now) + DAY_MS);
+        fail("Too many access requests right now. Try again later.", {
+            errorCode: "access_request_rate_limited",
+            statusCode: 429,
+            details: { retryAt },
+        });
+    }
+}
+async function deliverAccessRequest(reg, resource, request) {
+    const recipients = await requestRecipients(reg, resource, request);
+    const title = resourceTitle(reg, resource);
+    const requesterName = request.requesterName || request.requesterEmail;
+    const reviewPath = accessRequestReviewPath(request.id);
+    const sendsEmail = await isEmailConfigured();
+    const reviewUrl = resolveShareNotificationUrl(undefined, reviewPath);
+    const resourceUrl = resolveShareNotificationUrl(undefined, resourcePath(reg, resource));
+    const app = sendsEmail ? await emailBrand(reg, resource) : null;
+    const key = `access-request:${request.id}:${request.generation}`;
+    const delivery = {
+        recipients: recipients.length,
+        inbox: 0,
+        email: 0,
+        failed: 0,
+    };
+    for (const recipient of recipients) {
+        try {
+            const result = await notifyWithDelivery({
+                severity: "info",
+                title: `${requesterName} is asking for access to "${title}"`,
+                body: request.note ?? undefined,
+                // Only the inbox: the email channel would go to workspace-wide
+                // recipients, and the email below already reaches this person.
+                channels: ["inbox"],
+                metadata: {
+                    link: reviewPath,
+                    kind: "access-request",
+                    resourceType: request.resourceType,
+                    resourceId: request.resourceId,
+                    requestId: request.id,
+                },
+                idempotencyKey: key,
+            }, { owner: recipient });
+            if (result.notification)
+                delivery.inbox++;
+            else
+                delivery.failed++;
+        }
+        catch (err) {
+            delivery.failed++;
+            console.error("[access-requests] request notification failed:", err);
+        }
+        if (!app)
+            continue;
+        try {
+            const { subject, html, text } = await renderTransactionalEmail(CORE_ACCESS_REQUESTED_EMAIL_ID, {
+                recipientEmail: recipient,
+                requester: { name: requesterName, email: request.requesterEmail },
+                resource: {
+                    type: request.resourceType,
+                    label: reg.displayName,
+                    title,
+                    url: resourceUrl,
+                },
+                reviewUrl,
+                note: request.note ?? undefined,
+                app,
+            });
+            const sent = await sendEmail({
+                to: recipient,
+                subject,
+                html,
+                text,
+                replyTo: request.requesterEmail,
+                templateId: CORE_ACCESS_REQUESTED_EMAIL_ID,
+                idempotencyKey: `${key}:${recipient}`,
+            });
+            if (sent.status === "sent")
+                delivery.email++;
+        }
+        catch (err) {
+            delivery.failed++;
+            console.error("[access-requests] request email failed:", err);
+        }
+    }
+    return delivery;
+}
+/**
+ * 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 async function requestResourceAccess(input) {
+    const reg = requireShareableResource(input.resourceType);
+    if (!reg.accessRequests) {
+        fail(`${reg.displayName} doesn't take access requests.`, {
+            errorCode: "access_requests_unsupported",
+        });
+    }
+    const requesterEmail = requireSignedIn("Sign in to request access.");
+    const status = await resolveAccessStatus(input.resourceType, input.resourceId);
+    if (status.state === "allowed" || status.state === "trashed") {
+        return { state: "allowed" };
+    }
+    if (status.state !== "denied") {
+        fail(`This ${reg.displayName.toLowerCase()} doesn't exist.`, {
+            errorCode: "resource_missing",
+            statusCode: 404,
+        });
+    }
+    const now = Date.now();
+    const existing = openRequestFor(await findAccessRequest(input.resourceType, input.resourceId, requesterEmail), now);
+    if (existing)
+        return { state: "requested", request: existing, sent: false };
+    const resource = await loadResource(reg, input.resourceId);
+    const ownerEmail = String(resource?.ownerEmail ?? "")
+        .trim()
+        .toLowerCase();
+    if (!resource || !ownerEmail) {
+        fail(`This ${reg.displayName.toLowerCase()} doesn't exist.`, {
+            errorCode: "resource_missing",
+            statusCode: 404,
+        });
+    }
+    const profile = await getUserProfile(requesterEmail);
+    const note = input.note?.trim().slice(0, ACCESS_REQUEST_NOTE_MAX_LENGTH);
+    const { request, opened } = await openAccessRequest({
+        resourceType: input.resourceType,
+        resourceId: input.resourceId,
+        requesterEmail,
+        requesterName: profile.name?.trim() || null,
+        ownerEmail,
+        note: note || null,
+        now,
+        declinedCooldownStart: now - ACCESS_REQUEST_DECLINE_COOLDOWN_MS,
+        sendWindowStart: now - ACCESS_REQUEST_SEND_WINDOW_MS,
+    });
+    const view = openRequestFor(request, now);
+    if (!opened || !view) {
+        if (view)
+            return { state: "requested", request: view, sent: false };
+        fail("This request changed while it was being sent. Try again.", {
+            errorCode: "access_request_conflict",
+            statusCode: 409,
+        });
+    }
+    // The limits count the request just opened, so requests made at the same
+    // moment can't all pass a count taken before any of them existed.
+    let delivery;
+    try {
+        await enforceRequestLimits(requesterEmail, ownerEmail, now);
+        delivery = await deliverAccessRequest(reg, resource, request);
+        if (delivery.inbox + delivery.email === 0) {
+            fail("The owner couldn't be notified. Try again in a moment.", {
+                errorCode: "access_request_undelivered",
+                statusCode: 503,
+            });
+        }
+    }
+    catch (err) {
+        await deleteAccessRequest(request.id, request.generation, request.requestedAt);
+        throw err;
+    }
+    await recordAccessRequestDelivery(request.id, request.generation, {
+        ...delivery,
+    });
+    return { state: "requested", request: view, sent: true };
+}
+// Someone who can't manage the resource learns nothing from a request id,
+// not even that it exists.
+function requestNotFound() {
+    fail("This request doesn't exist, or you can't manage access to it.", {
+        errorCode: "access_request_not_found",
+        statusCode: 404,
+    });
+}
+async function loadReviewableRequest(requestId) {
+    requireSignedIn("Sign in to review access requests.");
+    const request = await getAccessRequest(requestId);
+    if (!request)
+        requestNotFound();
+    const access = await resolveAccess(request.resourceType, request.resourceId);
+    if (access?.role !== "owner" && access?.role !== "admin")
+        requestNotFound();
+    return {
+        request,
+        reg: requireShareableResource(request.resourceType),
+        resource: access.resource,
+    };
+}
+function toReview(reg, resource, request) {
+    return {
+        id: request.id,
+        generation: request.generation,
+        state: request.state,
+        requester: { email: request.requesterEmail, name: request.requesterName },
+        note: request.note,
+        requestedAt: iso(request.requestedAt),
+        decidedAt: request.decidedAt === null ? null : iso(request.decidedAt),
+        grantedRole: request.grantedRole,
+        resource: {
+            type: request.resourceType,
+            id: request.resourceId,
+            label: reg.displayName,
+            title: resourceTitle(reg, resource),
+            path: resourcePath(reg, resource) ?? null,
+        },
+    };
+}
+/** A request, for someone who manages access to its resource. */
+export async function getAccessRequestReview(requestId) {
+    const { request, reg, resource } = await loadReviewableRequest(requestId);
+    return toReview(reg, resource, request);
+}
+/** Pending requests for one resource, for someone who manages its access. */
+export async function listResourceAccessRequests(resourceType, resourceId) {
+    const reg = requireShareableResource(resourceType);
+    const access = await resolveAccess(resourceType, resourceId, undefined, {
+        skipResourceBody: true,
+    });
+    if (access?.role !== "owner" && access?.role !== "admin") {
+        fail(`You can't manage access to this ${reg.displayName.toLowerCase()}.`, {
+            errorCode: "forbidden",
+            statusCode: 403,
+        });
+    }
+    if (!reg.accessRequests)
+        return { requests: [], hasMore: false };
+    const rows = await listPendingAccessRequests(resourceType, resourceId, PENDING_LIST_LIMIT + 1);
+    return {
+        requests: rows
+            .slice(0, PENDING_LIST_LIMIT)
+            .map((row) => toReview(reg, access.resource, row)),
+        hasMore: rows.length > PENDING_LIST_LIMIT,
+    };
+}
+function staleRequest() {
+    fail("Someone already handled this request, or it changed. Reload it.", {
+        errorCode: "access_request_stale",
+        statusCode: 409,
+    });
+}
+async function sendAccessGrantedEmail(reg, resource, request, approverEmail, role) {
+    try {
+        // `isEmailConfigured` is false for a broken setup too, which the approver
+        // needs to hear about rather than read as "no email here".
+        const readiness = await getEmailReadiness();
+        if (readiness.status === "not-configured")
+            return "skipped";
+        if (readiness.status !== "ready") {
+            throw new Error(`Email is ${readiness.status} (provider: ${readiness.provider}).`);
+        }
+        const approver = await getUserProfile(approverEmail);
+        const { subject, html, text } = await renderTransactionalEmail(CORE_ACCESS_GRANTED_EMAIL_ID, {
+            recipientEmail: request.requesterEmail,
+            approver: {
+                name: approver.name?.trim() || approverEmail,
+                email: approverEmail,
+            },
+            resource: {
+                type: request.resourceType,
+                label: reg.displayName,
+                title: resourceTitle(reg, resource),
+                url: resolveShareNotificationUrl(undefined, resourcePath(reg, resource), getAppProductionUrl()),
+            },
+            role,
+            app: await emailBrand(reg, resource),
+        });
+        const sent = await sendEmail({
+            to: request.requesterEmail,
+            subject,
+            html,
+            text,
+            templateId: CORE_ACCESS_GRANTED_EMAIL_ID,
+            idempotencyKey: `access-granted:${request.id}:${request.generation}`,
+        });
+        return sent.status === "sent" ? "sent" : "skipped";
+    }
+    catch (err) {
+        console.error("[access-requests] access-granted email failed:", err);
+        return "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 async function approveAccessRequest(input) {
+    const { request, reg, resource } = await loadReviewableRequest(input.requestId);
+    if (request.state !== "pending" || request.generation !== input.generation) {
+        staleRequest();
+    }
+    const approver = viewerEmail();
+    const exec = getDbExec();
+    const grant = await exec.transaction((tx) => withDbExec(tx, async () => {
+        const granted = await grantResourceAccess({
+            resourceType: request.resourceType,
+            resourceId: request.resourceId,
+            principalType: "user",
+            principalId: request.requesterEmail,
+            role: input.role,
+            keepStrongerRole: true,
+        });
+        const decided = await decideAccessRequest({
+            id: request.id,
+            generation: request.generation,
+            state: "approved",
+            decidedBy: approver,
+            grantedRole: granted.role,
+            now: Date.now(),
+        }, tx);
+        if (!decided)
+            staleRequest();
+        return granted;
+    }));
+    await announceResourceAccessChange(request.resourceType, request.resourceId, grant.extensionTargetsBefore);
+    const email = await sendAccessGrantedEmail(reg, resource, request, approver, grant.role);
+    return { state: "approved", role: grant.role, email };
+}
+/** Closes a request without granting anything or telling the requester. */
+export async function declineAccessRequest(input) {
+    const { request } = await loadReviewableRequest(input.requestId);
+    if (request.state !== "pending" || request.generation !== input.generation) {
+        staleRequest();
+    }
+    const decided = await decideAccessRequest({
+        id: request.id,
+        generation: request.generation,
+        state: "declined",
+        decidedBy: viewerEmail(),
+        grantedRole: null,
+        now: Date.now(),
+    });
+    if (!decided)
+        staleRequest();
+    return { state: "declined" };
+}

package/dist/sharing/access.d.ts

@@ -26,8 +26,9 @@ export interface ResolvedAccess {
  * Minimal resource shape returned when a caller opts into a projected access
  * load via `{ skipResourceBody: true }`. Contains exactly the columns the
  * access-decision logic itself reads — identity, ownership, org scope, and
- * visibility — never a resource type's heavy body columns (`data`,
- * `content`, and similar blobs).
+ * visibility, plus any columns the registration's availability rule reads —
+ * never a resource type's heavy body columns (`data`, `content`, and similar
+ * blobs).
  */
 export interface AccessProjectedResource {
     id: string;
@@ -42,12 +43,45 @@ export interface ResolvedAccessProjected {
 export interface ResolveAccessOptions {
     skipResourceBody?: boolean;
 }
+/**
+ * Whether a loaded row passes its registration's availability rule. A row
+ * loaded without an availability column (an older schema) counts as
+ * available, the same as a registration without a rule.
+ */
+export declare function isResourceAvailable(reg: ShareableResourceRegistration, resource: any): boolean;
 export declare function resolveAccess(resourceType: string, resourceId: string, rawCtx?: AccessContext, options?: {
     skipResourceBody?: false;
 }): Promise<ResolvedAccess | null>;
 export declare function resolveAccess(resourceType: string, resourceId: string, rawCtx: AccessContext | undefined, options: {
     skipResourceBody: true;
 }): Promise<ResolvedAccessProjected | null>;
+/**
+ * What a link to a shareable resource can honestly say to the person who
+ * opened it.
+ *
+ * - `allowed`: they can open it.
+ * - `trashed`: they could open it, but it fails the registration's
+ *   availability rule (for example it is in the trash).
+ * - `denied`: they are signed in, can't open it, and it exists.
+ * - `missing`: they are signed in and it doesn't exist, or it is unavailable
+ *   and they can't open it, so trash looks the same as deleted.
+ * - `signed-out`: nobody is signed in, so nothing about it is revealed, not
+ *   even whether it exists or is public.
+ */
+export type ResourceAccessState = "allowed" | "trashed" | "denied" | "missing" | "signed-out";
+export interface ResourceAccessStatus {
+    state: ResourceAccessState;
+    /** The viewer's role, only when they can open the resource. */
+    role?: ResolvedAccess["role"];
+}
+/**
+ * Resolves a link's {@link ResourceAccessState} for the current viewer. It
+ * never returns the resource's title, owner, visibility, or workspace, and
+ * database failures stay errors rather than reading as `missing`. A
+ * signed-out visitor gets `signed-out` before any row is read, so nothing
+ * about the link, including whether it exists, depends on the resource.
+ */
+export declare function resolveAccessStatus(resourceType: string, resourceId: string, ctx?: AccessContext): Promise<ResourceAccessStatus>;
 export declare function assertAccess(resourceType: string, resourceId: string, minRole?: ShareRole | "owner", ctx?: AccessContext, options?: {
     skipResourceBody?: false;
 }): Promise<ResolvedAccess>;

package/dist/sharing/access.js

@@ -276,24 +276,46 @@ function selectExistingColumns(columns, omittedColumnNames) {
     }
     return selection;
 }
-function projectedAccessColumns(resourceTable) {
-    return {
+function projectedAccessColumns(reg) {
+    const resourceTable = reg.resourceTable;
+    const columns = {
         id: resourceTable.id,
         ownerEmail: resourceTable.ownerEmail,
         orgId: resourceTable.orgId,
         visibility: resourceTable.visibility,
     };
+    for (const key of [
+        ...(reg.availability?.columns ?? []),
+        ...(reg.fallbackAccessContext?.columns ?? []),
+    ]) {
+        if (resourceTable[key])
+            columns[key] = resourceTable[key];
+    }
+    return columns;
+}
+/**
+ * Whether a loaded row passes its registration's availability rule. A row
+ * loaded without an availability column (an older schema) counts as
+ * available, the same as a registration without a rule.
+ */
+export function isResourceAvailable(reg, resource) {
+    if (!reg.availability)
+        return true;
+    if (reg.availability.columns.some((column) => !(column in resource))) {
+        return true;
+    }
+    return reg.availability.isAvailable(resource);
 }
 function hasDynamicPublicAccessRoleResolver(reg) {
     return typeof reg.publicAccessRole === "function";
 }
 async function loadResourceForAccess(reg, resourceId, options = {}) {
     const db = reg.getDb();
+    // Hooks that receive the row may read any column, so they get all of it.
     const useProjection = options.skipResourceBody === true &&
-        !hasDynamicPublicAccessRoleResolver(reg);
-    const projectedColumns = useProjection
-        ? projectedAccessColumns(reg.resourceTable)
-        : null;
+        !hasDynamicPublicAccessRoleResolver(reg) &&
+        !reg.canManageAccess;
+    const projectedColumns = useProjection ? projectedAccessColumns(reg) : null;
     const omittedColumnNames = new Set();
     for (let attempt = 0; attempt < 12; attempt++) {
         try {
@@ -316,11 +338,13 @@ async function loadResourceForAccess(reg, resourceId, options = {}) {
     throw new Error(`Could not load ${reg.type} ${resourceId}: too many missing resource columns`);
 }
 export async function resolveAccess(resourceType, resourceId, rawCtx = currentAccess(), options = {}) {
-    return rawCtx.transaction
-        ? withDbExec(rawCtx.transaction, () => resolveAccessImpl(resourceType, resourceId, rawCtx, options))
-        : resolveAccessImpl(resourceType, resourceId, rawCtx, options);
+    const { access } = await inAccessTransaction(rawCtx, () => loadAndResolveAccess(resourceType, resourceId, rawCtx, options));
+    return access;
+}
+function inAccessTransaction(ctx, run) {
+    return ctx.transaction ? withDbExec(ctx.transaction, run) : run();
 }
-async function resolveAccessImpl(resourceType, resourceId, rawCtx = currentAccess(), options = {}) {
+async function loadAndResolveAccess(resourceType, resourceId, rawCtx, options) {
     const registered = requireShareableResource(resourceType);
     const transaction = rawCtx.transaction ?? getScopedDbExec();
     const transactionDb = transaction
@@ -336,7 +360,14 @@ async function resolveAccessImpl(resourceType, resourceId, rawCtx = currentAcces
     const ctx = resolveRegisteredAccessContext(reg, transactionCtx);
     const resource = await loadResourceForAccess(reg, resourceId, options);
     if (!resource)
-        return null;
+        return { access: null, resource: null, reg };
+    return {
+        access: await accessToResource(reg, resourceId, resource, ctx),
+        resource,
+        reg,
+    };
+}
+async function accessToResource(reg, resourceId, resource, ctx) {
     const { userEmail } = ctx;
     const normalizedUserEmail = normalizeEmailForAccess(userEmail);
     if (normalizedUserEmail &&
@@ -364,6 +395,37 @@ async function resolveAccessImpl(resourceType, resourceId, rawCtx = currentAcces
         return { role, resource };
     return null;
 }
+/**
+ * Resolves a link's {@link ResourceAccessState} for the current viewer. It
+ * never returns the resource's title, owner, visibility, or workspace, and
+ * database failures stay errors rather than reading as `missing`. A
+ * signed-out visitor gets `signed-out` before any row is read, so nothing
+ * about the link, including whether it exists, depends on the resource.
+ */
+export async function resolveAccessStatus(resourceType, resourceId, ctx = currentAccess()) {
+    requireShareableResource(resourceType);
+    if (!normalizeEmailForAccess(ctx.userEmail))
+        return { state: "signed-out" };
+    return inAccessTransaction(ctx, async () => {
+        const loaded = await loadAndResolveAccess(resourceType, resourceId, ctx, {
+            skipResourceBody: true,
+        });
+        const { resource, reg } = loaded;
+        if (!resource)
+            return { state: "missing" };
+        let access = loaded.access;
+        if (!access && reg.fallbackAccessContext) {
+            const fallback = await reg.fallbackAccessContext.resolve(resource, ctx);
+            if (fallback) {
+                access = await accessToResource(reg, resourceId, resource, resolveRegisteredAccessContext(reg, fallback));
+            }
+        }
+        const available = isResourceAvailable(reg, resource);
+        if (!access)
+            return { state: available ? "denied" : "missing" };
+        return { state: available ? "allowed" : "trashed", role: access.role };
+    });
+}
 async function highestShareRole(reg, resourceId, ctx, resource) {
     const { userEmail, orgId } = ctx;
     const normalizedUserEmail = normalizeEmailForAccess(userEmail);
@@ -410,7 +472,7 @@ async function highestShareRole(reg, resourceId, ctx, resource) {
     return best;
 }
 export async function assertAccess(resourceType, resourceId, minRole = "viewer", ctx = currentAccess(), options = {}) {
-    const access = await resolveAccessImpl(resourceType, resourceId, ctx, options);
+    const { access } = await loadAndResolveAccess(resourceType, resourceId, ctx, options);
     if (!access) {
         throw new ForbiddenError(`No access to ${resourceType} ${resourceId}`);
     }