@objectstack/plugin-sharing 6.8.1 → 6.9.0

package/src/share-link-routes.ts

@@ -0,0 +1,266 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * REST surface for ShareLinkService.
+ *
+ *   POST   /api/v1/share-links                 → create a link
+ *   GET    /api/v1/share-links                 → list links (?object, ?recordId, ?includeRevoked)
+ *   DELETE /api/v1/share-links/:idOrToken      → revoke
+ *   GET    /api/v1/share-links/:token/resolve  → resolve token, returns { record, link, redactFields }
+ *
+ * The resolve route is intentionally public — it's the only endpoint
+ * holders of a token need. It does:
+ *
+ *   1. Look up the row by token (via ShareLinkService.resolveToken,
+ *      which gates audience / expiry / password and stamps usage).
+ *   2. Fetch the underlying record with a SYSTEM context (so the read
+ *      bypasses normal RLS — the token IS the authorisation).
+ *   3. Strip `redactFields` from the record before returning.
+ *
+ * For browser-rendered share pages, the front-end calls this endpoint
+ * and renders the response read-only.
+ */
+
+import type { IHttpServer, IHttpRequest, IHttpResponse, RouteHandler } from '@objectstack/spec/contracts';
+import type { ShareLinkExecutionContext } from '@objectstack/spec/contracts';
+import type { ShareLinkService } from './share-link-service.js';
+import type { SharingEngine } from './sharing-service.js';
+
+const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
+
+export interface ShareLinkRoutesOptions {
+  basePath?: string;
+  /** Read caller identity for authenticated routes. */
+  contextFromRequest?: (req: IHttpRequest) => ShareLinkExecutionContext;
+}
+
+const defaultContext = (req: IHttpRequest): ShareLinkExecutionContext => {
+  const header = (name: string): string | undefined => {
+    const v = req.headers?.[name];
+    return Array.isArray(v) ? v[0] : v;
+  };
+  return {
+    userId: header('x-user-id'),
+    tenantId: header('x-tenant-id'),
+  };
+};
+
+function sendError(res: IHttpResponse, status: number, code: string, message: string) {
+  res.status(status).json({ error: { code, message } });
+}
+
+/** Strip `redactFields` from a record (also removes from nested arrays of objects). */
+function applyRedaction(record: any, redactFields: string[]): any {
+  if (!record || typeof record !== 'object' || redactFields.length === 0) return record;
+  if (Array.isArray(record)) return record.map((r) => applyRedaction(r, redactFields));
+  const out: any = {};
+  for (const [k, v] of Object.entries(record)) {
+    if (redactFields.includes(k)) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+export function registerShareLinkRoutes(
+  http: IHttpServer,
+  service: ShareLinkService,
+  engine: SharingEngine,
+  opts: ShareLinkRoutesOptions = {},
+): void {
+  const base = opts.basePath ?? '/api/v1/share-links';
+  const ctxOf = opts.contextFromRequest ?? defaultContext;
+
+  // ── CREATE ─────────────────────────────────────────────────────
+  http.post(base, (async (req, res) => {
+    try {
+      const ctx = ctxOf(req);
+      const body: any = req.body ?? {};
+      if (!body.object || !body.recordId) {
+        return sendError(res, 400, 'VALIDATION_FAILED', 'object and recordId are required');
+      }
+      const link = await service.createLink(
+        {
+          object: body.object,
+          recordId: body.recordId,
+          permission: body.permission,
+          audience: body.audience,
+          expiresAt: body.expiresAt ?? null,
+          emailAllowlist: body.emailAllowlist,
+          password: body.password,
+          redactFields: body.redactFields,
+          label: body.label,
+        },
+        ctx,
+      );
+      // Echo the token in the create response only — the listing
+      // endpoint also returns it (admins need to copy/recreate URLs),
+      // but downstream API consumers typically derive the public URL
+      // from `link.token` immediately.
+      await res.status(201).json({ link });
+    } catch (err: any) {
+      sendError(res, err?.status ?? 500, err?.code ?? 'INTERNAL', err?.message ?? 'Failed to create link');
+    }
+  }) satisfies RouteHandler);
+
+  // ── LIST ───────────────────────────────────────────────────────
+  http.get(base, (async (req, res) => {
+    try {
+      const ctx = ctxOf(req);
+      const q = req.query ?? {};
+      const link = await service.listLinks(
+        {
+          object: typeof q.object === 'string' ? q.object : undefined,
+          recordId: typeof q.recordId === 'string' ? q.recordId : undefined,
+          createdBy: typeof q.createdBy === 'string' ? q.createdBy : undefined,
+          includeRevoked: q.includeRevoked === 'true' || q.includeRevoked === '1',
+        },
+        ctx,
+      );
+      await res.json({ links: link });
+    } catch (err: any) {
+      sendError(res, err?.status ?? 500, err?.code ?? 'INTERNAL', err?.message ?? 'Failed to list links');
+    }
+  }) satisfies RouteHandler);
+
+  // ── REVOKE ─────────────────────────────────────────────────────
+  http.delete(`${base}/:idOrToken`, (async (req, res) => {
+    try {
+      const ctx = ctxOf(req);
+      await service.revokeLink(req.params.idOrToken, ctx);
+      await res.status(200).json({ ok: true });
+    } catch (err: any) {
+      sendError(res, err?.status ?? 500, err?.code ?? 'INTERNAL', err?.message ?? 'Failed to revoke link');
+    }
+  }) satisfies RouteHandler);
+
+  // ── PUBLIC RESOLVE ────────────────────────────────────────────
+  //
+  // No `ctxOf` here — the token IS the authorisation. We still allow
+  // probes from a signed-in user so audience=signed_in is satisfiable.
+  http.get(`${base}/:token/resolve`, (async (req, res) => {
+    try {
+      const q = req.query ?? {};
+      const signedInUserId = (() => {
+        const v = req.headers?.['x-user-id'];
+        return Array.isArray(v) ? v[0] : v;
+      })();
+      const recipientEmail = typeof q.email === 'string' ? q.email : undefined;
+      const providedPassword =
+        typeof q.password === 'string'
+          ? q.password
+          : (() => {
+              const v = req.headers?.['x-share-password'];
+              return Array.isArray(v) ? v[0] : v;
+            })();
+
+      const resolved = await service.resolveToken(req.params.token, {
+        signedInUserId,
+        recipientEmail,
+        providedPassword,
+      });
+      if (!resolved) {
+        // Probe row to give a more useful status code (401 vs 404 vs 410).
+        const probe = await engine.find('sys_share_link', {
+          where: { token: req.params.token },
+          limit: 1,
+          context: SYSTEM_CTX,
+        } as any);
+        const row = Array.isArray(probe) && probe[0] ? (probe[0] as any) : null;
+        if (row && !row.revoked_at && (!row.expires_at || Date.parse(row.expires_at) > Date.now())) {
+          if (row.password_hash) {
+            return sendError(
+              res,
+              401,
+              providedPassword ? 'WRONG_PASSWORD' : 'NEEDS_PASSWORD',
+              providedPassword ? 'Incorrect password' : 'This link requires a password',
+            );
+          }
+          if (row.audience === 'signed_in' && !signedInUserId) {
+            return sendError(res, 401, 'SIGN_IN_REQUIRED', 'Please sign in to view this link');
+          }
+        }
+        if (row && (row.revoked_at || (row.expires_at && Date.parse(row.expires_at) <= Date.now()))) {
+          return sendError(res, 410, 'EXPIRED_OR_REVOKED', 'Share link has expired or been revoked');
+        }
+        return sendError(res, 404, 'INVALID_OR_EXPIRED', 'Share link is invalid, expired, or revoked');
+      }
+
+      // Fetch the underlying record with system context — the token
+      // gates access, RLS does not.
+      const rows = await engine.find(resolved.link.object_name, {
+        where: { id: resolved.link.record_id },
+        limit: 1,
+        context: SYSTEM_CTX,
+      } as any);
+      const record = Array.isArray(rows) && rows[0] ? rows[0] : null;
+      if (!record) {
+        return sendError(res, 410, 'RECORD_GONE', 'The shared record no longer exists');
+      }
+
+      await res.json({
+        record: applyRedaction(record, resolved.redactFields),
+        link: {
+          id: resolved.link.id,
+          token: resolved.link.token,
+          object_name: resolved.link.object_name,
+          record_id: resolved.link.record_id,
+          permission: resolved.link.permission,
+          audience: resolved.link.audience,
+          expires_at: resolved.link.expires_at,
+          label: resolved.link.label,
+          created_at: resolved.link.created_at,
+        },
+        redactFields: resolved.redactFields,
+      });
+    } catch (err: any) {
+      sendError(res, err?.status ?? 500, err?.code ?? 'INTERNAL', err?.message ?? 'Failed to resolve link');
+    }
+  }) satisfies RouteHandler);
+
+  // ──────────────────────────────────────────────────────────────
+  // Object-specific related-records lookup.
+  //
+  // Some objects only make sense alongside their children — most
+  // notably `ai_conversations` and the `ai_messages` they own. Rather
+  // than baking every relationship into the resolver, we expose a
+  // narrow, opt-in `GET /:token/messages` route that:
+  //
+  //   1. Re-validates the capability token (so revocation / expiry
+  //      kicks in even after the original resolve).
+  //   2. Confirms the shared record really is an `ai_conversations`.
+  //   3. Returns the conversation's messages, ordered by creation.
+  //
+  // Other object kinds can register additional public endpoints
+  // following the same pattern.
+  // ──────────────────────────────────────────────────────────────
+  http.get(`${base}/:token/messages`, (async (req, res) => {
+    try {
+      const password =
+        typeof req.query?.password === 'string' ? (req.query.password as string) : undefined;
+      const resolved = await service.resolveToken(req.params.token, { providedPassword: password });
+      if (!resolved) {
+        sendError(res, 404, 'NOT_FOUND', 'Share link not found');
+        return;
+      }
+      if (resolved.link.object_name !== 'ai_conversations') {
+        sendError(res, 400, 'UNSUPPORTED', 'This share link does not expose messages');
+        return;
+      }
+      const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
+      const rows = await engine.find('ai_messages', {
+        where: { conversation_id: resolved.link.record_id },
+        sort: [{ field: 'created_at', direction: 'asc' }],
+        limit: 500,
+        context: SYSTEM_CTX,
+      } as any);
+      res.status(200).json({ data: rows ?? [] });
+    } catch (err: any) {
+      sendError(
+        res,
+        err?.status ?? 500,
+        err?.code ?? 'INTERNAL',
+        err?.message ?? 'Failed to load messages',
+      );
+    }
+  }) satisfies RouteHandler);
+}

package/src/share-link-service.test.ts

@@ -0,0 +1,166 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ShareLinkService } from './share-link-service.js';
+
+interface FakeRow { [k: string]: any }
+
+function makeFakeEngine(schemas: Record<string, any>) {
+  const tables: Record<string, FakeRow[]> = {};
+  const ensure = (name: string) => (tables[name] ??= []);
+
+  function matches(row: FakeRow, filter: any): boolean {
+    if (!filter || typeof filter !== 'object') return true;
+    for (const [k, v] of Object.entries(filter)) {
+      if (row[k] !== v) return false;
+    }
+    return true;
+  }
+
+  return {
+    _tables: tables,
+    getSchema(name: string) { return schemas[name]; },
+    async find(object: string, options?: any) {
+      const filter = options?.filter ?? options?.where;
+      return ensure(object).filter(r => matches(r, filter));
+    },
+    async insert(object: string, data: any) {
+      const row = { ...data };
+      ensure(object).push(row);
+      return row;
+    },
+    async update(object: string, idOrData: any, dataOrOptions?: any) {
+      const data = typeof idOrData === 'object' ? idOrData : dataOrOptions;
+      const id = typeof idOrData === 'object' ? idOrData.id : idOrData;
+      const table = ensure(object);
+      const i = table.findIndex(r => r.id === id);
+      if (i >= 0) table[i] = { ...table[i], ...data };
+      return table[i];
+    },
+    async delete() { return { id: null }; },
+  };
+}
+
+const SCHEMAS = {
+  sys_share_link: { name: 'sys_share_link', fields: {} },
+  // The opt-in target.
+  ai_conversations: {
+    name: 'ai_conversations',
+    publicSharing: {
+      enabled: true,
+      allowedAudiences: ['link_only', 'signed_in'],
+      allowedPermissions: ['view'],
+      redactFields: ['metadata'],
+      maxExpiryDays: 30,
+    },
+    fields: { id: {}, title: {}, metadata: {} },
+  },
+  // Sharing not enabled.
+  sys_user: {
+    name: 'sys_user',
+    fields: { id: {}, email: {} },
+  },
+};
+
+describe('ShareLinkService', () => {
+  let engine: ReturnType<typeof makeFakeEngine>;
+  let service: ShareLinkService;
+
+  beforeEach(() => {
+    engine = makeFakeEngine(SCHEMAS);
+    // Seed a real conversation row so existence checks pass.
+    engine._tables.ai_conversations = [{ id: 'c1', title: 'Demo' }];
+    service = new ShareLinkService({ engine: engine as any });
+  });
+
+  it('mints a link for an opt-in object', async () => {
+    const link = await service.createLink(
+      {
+        object: 'ai_conversations',
+        recordId: 'c1',
+        audience: 'link_only',
+        permission: 'view',
+      },
+      { userId: 'u1' },
+    );
+    expect(link.token).toMatch(/^[A-Za-z0-9_-]{20,}$/);
+    expect(link.permission).toBe('view');
+    expect(link.audience).toBe('link_only');
+    expect(engine._tables.sys_share_link).toHaveLength(1);
+  });
+
+  it('rejects objects that did not opt in', async () => {
+    await expect(
+      service.createLink(
+        { object: 'sys_user', recordId: 'u1', audience: 'link_only', permission: 'view' },
+        { userId: 'u1' },
+      ),
+    ).rejects.toThrow(/sharing/i);
+  });
+
+  it('rejects a permission outside the allow-list', async () => {
+    await expect(
+      service.createLink(
+        {
+          object: 'ai_conversations',
+          recordId: 'c1',
+          audience: 'link_only',
+          permission: 'edit',
+        },
+        { userId: 'u1' },
+      ),
+    ).rejects.toThrow(/permission/i);
+  });
+
+  it('resolves a freshly minted token', async () => {
+    const link = await service.createLink(
+      {
+        object: 'ai_conversations',
+        recordId: 'c1',
+        audience: 'link_only',
+        permission: 'view',
+      },
+      { userId: 'u1' },
+    );
+    const resolved = await service.resolveToken(link.token);
+    expect(resolved).not.toBeNull();
+    expect(resolved!.link.record_id).toBe('c1');
+    expect(resolved!.redactFields).toContain('metadata');
+  });
+
+  it('returns null for an unknown token', async () => {
+    expect(await service.resolveToken('nope-not-a-real-token-xyz')).toBeNull();
+  });
+
+  it('refuses to resolve a revoked token', async () => {
+    const link = await service.createLink(
+      {
+        object: 'ai_conversations',
+        recordId: 'c1',
+        audience: 'link_only',
+        permission: 'view',
+      },
+      { userId: 'u1' },
+    );
+    await service.revokeLink(link.id, { userId: 'u1' });
+    expect(await service.resolveToken(link.token)).toBeNull();
+  });
+
+  it('refuses to resolve an expired token', async () => {
+    // Bypass createLink (it refuses past dates) by inserting directly.
+    const past = new Date(Date.now() - 60_000).toISOString();
+    engine._tables.sys_share_link = [
+      {
+        id: 'shl_expired',
+        token: 'expired-token-xyz-123',
+        object_name: 'ai_conversations',
+        record_id: 'c1',
+        permission: 'view',
+        audience: 'link_only',
+        expires_at: past,
+        revoked_at: null,
+      },
+    ];
+    expect(await service.resolveToken('expired-token-xyz-123')).toBeNull();
+  });
+});