@objectstack/plugin-sharing 7.3.0 → 7.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/plugin-sharing",
-  "version": "7.3.0",
+  "version": "7.4.1",
   "license": "Apache-2.0",
   "description": "Record-level sharing for ObjectStack — sys_record_share + middleware that enforces sharingModel + ISharingService.",
   "main": "dist/index.js",
@@ -13,10 +13,10 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "7.3.0",
-    "@objectstack/objectql": "7.3.0",
-    "@objectstack/platform-objects": "7.3.0",
-    "@objectstack/spec": "7.3.0"
+    "@objectstack/core": "7.4.1",
+    "@objectstack/objectql": "7.4.1",
+    "@objectstack/platform-objects": "7.4.1",
+    "@objectstack/spec": "7.4.1"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",

package/scripts/i18n-extract.config.ts

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Build-time only config for `os i18n extract` (ADR-0029 D8). Not deployed.
+ * The plugin owns the i18n extraction for the objects it owns; the
+ * `translations` baseline is this plugin's OWN generated bundles so re-running
+ * `--merge` preserves every hand-translated string. (Initial zh-CN/ja-JP/es-ES
+ * strings were seeded from @objectstack/platform-objects.)
+ *
+ *   os i18n extract packages/plugins/plugin-sharing/scripts/i18n-extract.config.ts \
+ *     --locales=zh-CN,ja-JP,es-ES --fill=default --objects-only \
+ *     --out=packages/plugins/plugin-sharing/src/translations
+ */
+
+import { defineStack } from '@objectstack/spec';
+import { SysRecordShare, SysSharingRule, SysShareLink } from '../src/objects/index.js';
+import { enObjects } from '../src/translations/en.objects.generated.js';
+import { zhCNObjects } from '../src/translations/zh-CN.objects.generated.js';
+import { jaJPObjects } from '../src/translations/ja-JP.objects.generated.js';
+import { esESObjects } from '../src/translations/es-ES.objects.generated.js';
+
+export default defineStack({
+  name: 'plugin-sharing-i18n-extract',
+  objects: [SysRecordShare, SysSharingRule, SysShareLink] as any,
+  translations: [
+    { en: { objects: enObjects } },
+    { 'zh-CN': { objects: zhCNObjects } },
+    { 'ja-JP': { objects: jaJPObjects } },
+    { 'es-ES': { objects: esESObjects } },
+  ],
+});

package/src/index.ts

@@ -9,7 +9,7 @@
  * authenticated execution context.
  */
 
-export { SysRecordShare, SysSharingRule, SysShareLink } from '@objectstack/platform-objects/security';
+export { SysRecordShare, SysSharingRule, SysShareLink } from './objects/index.js';
 export { SysDepartment, SysDepartmentMember } from '@objectstack/platform-objects/identity';
 export {
   SharingService,

package/src/objects/index.ts

@@ -0,0 +1,14 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Sharing objects owned by `@objectstack/plugin-sharing` (ADR-0029 K2).
+ *
+ * Moved here from the `@objectstack/platform-objects` monolith so the plugin
+ * owns its data model, behavior, and admin menu as one unit. The RBAC objects
+ * (role / permission-set / *-permission-set) live in
+ * `@objectstack/plugin-security`.
+ */
+
+export { SysRecordShare } from './sys-record-share.object.js';
+export { SysSharingRule } from './sys-sharing-rule.object.js';
+export { SysShareLink } from './sys-share-link.object.js';

package/src/objects/sys-record-share.object.ts

@@ -0,0 +1,229 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * sys_record_share — Per-Record Sharing Grant
+ *
+ * Bridges the ownership-only baseline established by `object.sharingModel`
+ * with the real-world need to delegate access to a single record. Each
+ * row says: "principal P has access level L on (object O, record R),
+ * because of source S (manual grant or rule)."
+ *
+ * Enforcement lives in `@objectstack/plugin-sharing`:
+ *   - For objects with `sharingModel: 'private'`, the engine middleware
+ *     AND-s `{$or:[{owner_id:userId},{id:{$in:[grantedRecordIds]}}]}`
+ *     into every `find` against that object.
+ *   - For objects with `sharingModel: 'private' | 'read'`, the same
+ *     middleware enforces edit/delete by checking ownership OR a share
+ *     row with `access_level in ('edit','full')`.
+ *
+ * Conventions:
+ *  - `object_name` is the short object name (e.g. `account`, `lead`).
+ *  - `recipient_type` mirrors `ShareRecipientType` from the spec
+ *    (`user` is enforced today; `group`/`role` are persisted for
+ *    forward-compatibility).
+ *  - `source = 'manual'` rows are created by a user via the REST
+ *    `POST /data/:object/:id/shares` endpoint. `source = 'rule'` rows
+ *    are materialised by the sharing-rule evaluator (future); the
+ *    `source_id` lets the evaluator reconcile stale grants.
+ *
+ * @namespace sys
+ */
+export const SysRecordShare = ObjectSchema.create({
+  name: 'sys_record_share',
+  label: 'Record Share',
+  pluralLabel: 'Record Shares',
+  icon: 'share',
+  isSystem: true,
+  managedBy: 'system',
+  description: 'Per-record sharing grant — extends OWD with explicit access',
+  titleFormat: '{object_name}/{record_id} → {recipient_id} ({access_level})',
+  compactLayout: ['object_name', 'record_id', 'recipient_id', 'access_level', 'source'],
+
+  listViews: {
+    granted_to_me: {
+      type: 'grid',
+      name: 'granted_to_me',
+      label: 'Granted to Me',
+      data: { provider: 'object', object: 'sys_record_share' },
+      columns: ['object_name', 'record_id', 'access_level', 'source', 'granted_by', 'created_at'],
+      filter: [
+        { field: 'recipient_type', operator: 'equals', value: 'user' },
+        { field: 'recipient_id', operator: 'equals', value: '{current_user_id}' },
+      ],
+      sort: [{ field: 'created_at', order: 'desc' }],
+      pagination: { pageSize: 50 },
+    },
+    granted_by_me: {
+      type: 'grid',
+      name: 'granted_by_me',
+      label: 'Granted by Me',
+      data: { provider: 'object', object: 'sys_record_share' },
+      columns: ['object_name', 'record_id', 'recipient_id', 'access_level', 'source', 'created_at'],
+      filter: [
+        { field: 'granted_by', operator: 'equals', value: '{current_user_id}' },
+      ],
+      sort: [{ field: 'created_at', order: 'desc' }],
+      pagination: { pageSize: 50 },
+    },
+    by_object: {
+      type: 'grid',
+      name: 'by_object',
+      label: 'By Object',
+      data: { provider: 'object', object: 'sys_record_share' },
+      columns: ['object_name', 'record_id', 'recipient_id', 'access_level', 'source', 'created_at'],
+      sort: [{ field: 'object_name', order: 'asc' }, { field: 'created_at', order: 'desc' }],
+      grouping: { fields: [{ field: 'object_name', order: 'asc', collapsed: false }] },
+      pagination: { pageSize: 100 },
+    },
+    manual_grants: {
+      type: 'grid',
+      name: 'manual_grants',
+      label: 'Manual Grants',
+      data: { provider: 'object', object: 'sys_record_share' },
+      columns: ['object_name', 'record_id', 'recipient_id', 'access_level', 'granted_by', 'reason', 'created_at'],
+      filter: [{ field: 'source', operator: 'equals', value: 'manual' }],
+      sort: [{ field: 'created_at', order: 'desc' }],
+      pagination: { pageSize: 50 },
+    },
+    rule_grants: {
+      type: 'grid',
+      name: 'rule_grants',
+      label: 'Rule Grants',
+      data: { provider: 'object', object: 'sys_record_share' },
+      columns: ['object_name', 'record_id', 'recipient_id', 'access_level', 'source_id', 'created_at'],
+      filter: [{ field: 'source', operator: 'in', value: ['rule', 'team', 'inherited'] }],
+      sort: [{ field: 'source_id', order: 'asc' }, { field: 'created_at', order: 'desc' }],
+      pagination: { pageSize: 50 },
+    },
+    all_shares: {
+      type: 'grid',
+      name: 'all_shares',
+      label: 'All',
+      data: { provider: 'object', object: 'sys_record_share' },
+      columns: ['object_name', 'record_id', 'recipient_type', 'recipient_id', 'access_level', 'source', 'created_at'],
+      sort: [{ field: 'created_at', order: 'desc' }],
+      pagination: { pageSize: 100 },
+    },
+  },
+
+  fields: {
+    id: Field.text({
+      label: 'Share ID',
+      required: true,
+      readonly: true,
+      group: 'System',
+    }),
+
+    // ── Target (which record is being shared) ────────────────────
+    object_name: Field.text({
+      label: 'Object',
+      required: true,
+      maxLength: 100,
+      description: 'Short object name of the shared record',
+      group: 'Target',
+    }),
+
+    record_id: Field.text({
+      label: 'Record',
+      required: true,
+      maxLength: 100,
+      description: 'Primary key of the shared record within object_name',
+      group: 'Target',
+    }),
+
+    // ── Recipient (who receives access) ──────────────────────────
+    recipient_type: Field.select(
+      ['user', 'group', 'role', 'role_and_subordinates', 'guest'],
+      {
+        label: 'Recipient Type',
+        required: true,
+        defaultValue: 'user',
+        description: 'Kind of principal that holds the grant',
+        group: 'Recipient',
+      },
+    ),
+
+    recipient_id: Field.text({
+      label: 'Recipient',
+      required: true,
+      maxLength: 100,
+      description: 'ID of the user/group/role that receives access',
+      group: 'Recipient',
+    }),
+
+    access_level: Field.select(
+      ['read', 'edit', 'full'],
+      {
+        label: 'Access Level',
+        required: true,
+        defaultValue: 'read',
+        description: 'What the recipient can do — read | edit | full (transfer/share/delete)',
+        group: 'Recipient',
+      },
+    ),
+
+    // ── Provenance ───────────────────────────────────────────────
+    source: Field.select(
+      ['manual', 'rule', 'team', 'inherited'],
+      {
+        label: 'Source',
+        required: true,
+        defaultValue: 'manual',
+        description: 'Why this grant exists — used by the rule evaluator to reconcile',
+        group: 'Provenance',
+      },
+    ),
+
+    source_id: Field.text({
+      label: 'Source ID',
+      required: false,
+      maxLength: 200,
+      description: 'Rule name / team id when source != manual',
+      group: 'Provenance',
+    }),
+
+    granted_by: Field.lookup('sys_user', {
+      label: 'Granted By',
+      required: false,
+      description: 'User that created the grant (manual only)',
+      group: 'Provenance',
+    }),
+
+    reason: Field.text({
+      label: 'Reason',
+      required: false,
+      maxLength: 500,
+      description: 'Optional free-text explanation surfaced to the recipient',
+      group: 'Provenance',
+    }),
+
+    // ── Lifecycle ────────────────────────────────────────────────
+    created_at: Field.datetime({
+      label: 'Created At',
+      required: true,
+      defaultValue: 'NOW()',
+      readonly: true,
+      group: 'System',
+    }),
+
+    updated_at: Field.datetime({
+      label: 'Updated At',
+      required: false,
+      group: 'System',
+    }),
+  },
+
+  indexes: [
+    // Hot path: "all records visible to user U on object O" — the
+    // middleware reads (object_name, recipient_type, recipient_id) to
+    // build the `id IN (...)` predicate on every find.
+    { fields: ['object_name', 'recipient_type', 'recipient_id'] },
+    // "all grants on this record" — used by the share-management UI
+    // and by canEdit() to look up explicit grants.
+    { fields: ['object_name', 'record_id'] },
+    // Reconciliation key for rule-driven shares.
+    { fields: ['source', 'source_id'] },
+  ],
+});

package/src/objects/sys-share-link.object.ts

@@ -0,0 +1,255 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * sys_share_link — Capability-Token Public Share Links
+ *
+ * Each row authorises read (or write) access to ONE record of ONE
+ * object via an opaque URL-safe token. Complements `sys_record_share`,
+ * which models principal-based grants (share with a specific user /
+ * team / role). A single record may have rows in both tables; the
+ * union determines effective access.
+ *
+ * Lifecycle:
+ *
+ *   1. `IShareLinkService.createLink` validates the request against the
+ *      target object's `publicSharing` whitelist and inserts a row.
+ *      Token is a 24-char URL-safe random string.
+ *
+ *   2. `IShareLinkService.resolveToken` (called from the public
+ *      `/api/v1/share-links/:token` middleware on every request)
+ *      verifies the row is not revoked / not expired, applies audience
+ *      / password gates, increments `use_count` + `last_used_at`, and
+ *      returns the effective redaction set.
+ *
+ *   3. `IShareLinkService.revokeLink` stamps `revoked_at`. Rows are
+ *      preserved for audit; resolveToken returns null after revocation.
+ *
+ * Conventions:
+ *  - `object_name` is the short object name (`account`, `ai_conversation`, …)
+ *  - `record_id` is the primary key of the target record within object_name
+ *  - `audience` mirrors `ShareLinkAudience` in spec/contracts; the
+ *    middleware enforces additional gating per audience
+ *  - `redact_fields` overlays on top of the schema-default redaction
+ *    set declared on `object.publicSharing.redactFields`
+ *
+ * managedBy: 'system' — admins inspect via the audit grid but all
+ * writes flow through `IShareLinkService` so the per-object opt-in,
+ * expiry caps, and audit hooks fire.
+ *
+ * @namespace sys
+ */
+export const SysShareLink = ObjectSchema.create({
+  name: 'sys_share_link',
+  label: 'Share Link',
+  pluralLabel: 'Share Links',
+  icon: 'link-2',
+  isSystem: true,
+  managedBy: 'system',
+  description: 'Opaque capability token granting access to a single record. Notion/Figma-style public link sharing.',
+  titleFormat: '{object_name}/{record_id} ({permission})',
+  compactLayout: ['object_name', 'record_id', 'permission', 'audience', 'expires_at', 'revoked_at'],
+
+  listViews: {
+    active_links: {
+      type: 'grid',
+      name: 'active_links',
+      label: 'Active',
+      data: { provider: 'object', object: 'sys_share_link' },
+      columns: ['object_name', 'record_id', 'permission', 'audience', 'expires_at', 'use_count', 'last_used_at'],
+      filter: [{ field: 'revoked_at', operator: 'isNull' }],
+      sort: [{ field: 'created_at', order: 'desc' }],
+      pagination: { pageSize: 100 },
+    },
+    by_me: {
+      type: 'grid',
+      name: 'by_me',
+      label: 'Created by Me',
+      data: { provider: 'object', object: 'sys_share_link' },
+      columns: ['object_name', 'record_id', 'permission', 'audience', 'expires_at', 'revoked_at'],
+      filter: [{ field: 'created_by', operator: 'equals', value: '{current_user_id}' }],
+      sort: [{ field: 'created_at', order: 'desc' }],
+      pagination: { pageSize: 100 },
+    },
+    revoked: {
+      type: 'grid',
+      name: 'revoked',
+      label: 'Revoked',
+      data: { provider: 'object', object: 'sys_share_link' },
+      columns: ['object_name', 'record_id', 'revoked_at', 'created_by'],
+      filter: [{ field: 'revoked_at', operator: 'isNotNull' }],
+      sort: [{ field: 'revoked_at', order: 'desc' }],
+      pagination: { pageSize: 50 },
+    },
+    all_links: {
+      type: 'grid',
+      name: 'all_links',
+      label: 'All',
+      data: { provider: 'object', object: 'sys_share_link' },
+      columns: ['object_name', 'record_id', 'permission', 'audience', 'expires_at', 'revoked_at', 'created_at'],
+      sort: [{ field: 'created_at', order: 'desc' }],
+      pagination: { pageSize: 200 },
+    },
+  },
+
+  fields: {
+    id: Field.text({
+      label: 'Link ID',
+      required: true,
+      readonly: true,
+      group: 'System',
+    }),
+
+    // ── Token (the secret) ───────────────────────────────────────
+    token: Field.text({
+      label: 'Token',
+      required: true,
+      maxLength: 64,
+      description: 'Opaque URL-safe random token (≥ 22 chars). The only secret in this row.',
+      group: 'Token',
+    }),
+
+    // ── Target ───────────────────────────────────────────────────
+    object_name: Field.text({
+      label: 'Object',
+      required: true,
+      maxLength: 100,
+      description: 'Short object name of the shared record (e.g. ai_conversation, contracts_contract)',
+      group: 'Target',
+    }),
+
+    record_id: Field.text({
+      label: 'Record',
+      required: true,
+      maxLength: 100,
+      description: 'Primary key of the shared record within object_name',
+      group: 'Target',
+    }),
+
+    // ── Access Policy ────────────────────────────────────────────
+    permission: Field.select(
+      [
+        { label: 'View',    value: 'view' },
+        { label: 'Comment', value: 'comment' },
+        { label: 'Edit',    value: 'edit' },
+      ],
+      {
+        label: 'Permission',
+        required: true,
+        defaultValue: 'view',
+        description: 'What the link holder can do with the record',
+        group: 'Access Policy',
+      },
+    ),
+
+    audience: Field.select(
+      [
+        { label: 'Public (indexable)', value: 'public' },
+        { label: 'Anyone with the link', value: 'link_only' },
+        { label: 'Signed-in users', value: 'signed_in' },
+        { label: 'Specific emails', value: 'email' },
+      ],
+      {
+        label: 'Audience',
+        required: true,
+        defaultValue: 'link_only',
+        description: 'Gating layer applied on top of the token check',
+        group: 'Access Policy',
+      },
+    ),
+
+    expires_at: Field.datetime({
+      label: 'Expires At',
+      description: 'When set, resolveToken returns null after this timestamp',
+      group: 'Access Policy',
+    }),
+
+    email_allowlist: Field.json({
+      label: 'Email Allowlist',
+      description: 'Lowercased addresses checked when audience=email',
+      group: 'Access Policy',
+    }),
+
+    password_hash: Field.text({
+      label: 'Password Hash',
+      maxLength: 256,
+      description: 'Argon2/bcrypt hash. When set, the UI prompts for a password before rendering.',
+      group: 'Access Policy',
+    }),
+
+    redact_fields: Field.json({
+      label: 'Per-Link Redactions',
+      description: 'Extra fields stripped from the response, on top of the object-default set',
+      group: 'Access Policy',
+    }),
+
+    label: Field.text({
+      label: 'Label',
+      maxLength: 200,
+      description: 'Free-text shown in the share dialog (e.g. "ACME Q3 contract")',
+      group: 'Metadata',
+    }),
+
+    // ── Lifecycle ────────────────────────────────────────────────
+    revoked_at: Field.datetime({
+      label: 'Revoked At',
+      readonly: true,
+      description: 'When set, the link is permanently disabled',
+      group: 'Lifecycle',
+    }),
+
+    created_by: Field.lookup('sys_user', {
+      label: 'Created By',
+      readonly: true,
+      description: 'Issuer of the link',
+      group: 'Lifecycle',
+    }),
+
+    created_at: Field.datetime({
+      label: 'Created At',
+      required: true,
+      defaultValue: 'NOW()',
+      readonly: true,
+      group: 'Lifecycle',
+    }),
+
+    last_used_at: Field.datetime({
+      label: 'Last Used At',
+      readonly: true,
+      description: 'Stamped by resolveToken; used by the dashboard to highlight active links',
+      group: 'Lifecycle',
+    }),
+
+    use_count: Field.number({
+      label: 'Use Count',
+      defaultValue: 0,
+      readonly: true,
+      description: 'Incremented by resolveToken on every successful resolution',
+      group: 'Lifecycle',
+    }),
+  },
+
+  indexes: [
+    // Hot path: resolveToken — one row lookup per public request.
+    { fields: ['token'], unique: true },
+    // Management UI: "all links for this record".
+    { fields: ['object_name', 'record_id'] },
+    // "Active links I issued".
+    { fields: ['created_by', 'revoked_at'] },
+    // Reaper for expired rows (background sweep).
+    { fields: ['expires_at'] },
+  ],
+
+  enable: {
+    trackHistory: false,
+    searchable: false,
+    apiEnabled: true,
+    // The /api/v1/share-links endpoints are the authoritative surface;
+    // the generic data API is exposed read-only for the admin grid.
+    apiMethods: ['get', 'list'],
+    trash: false,
+    mru: false,
+    clone: false,
+  },
+});