@objectstack/plugin-sharing 6.8.1 → 6.9.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/plugin-sharing@6.8.1 build /home/runner/work/framework/framework/packages/plugins/plugin-sharing
+> @objectstack/plugin-sharing@6.9.0 build /home/runner/work/framework/framework/packages/plugins/plugin-sharing
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     31.83 KB
-ESM dist/index.mjs.map 70.78 KB
-ESM ⚡️ Build success in 155ms
-CJS dist/index.js     33.33 KB
-CJS dist/index.js.map 70.80 KB
-CJS ⚡️ Build success in 159ms
+ESM dist/index.mjs     48.89 KB
+ESM dist/index.mjs.map 110.16 KB
+ESM ⚡️ Build success in 249ms
+CJS dist/index.js     50.56 KB
+CJS dist/index.js.map 110.16 KB
+CJS ⚡️ Build success in 258ms
 DTS Build start
-DTS ⚡️ Build success in 19261ms
-DTS dist/index.d.mts 11.90 KB
-DTS dist/index.d.ts  11.90 KB
+DTS ⚡️ Build success in 21619ms
+DTS dist/index.d.mts 15.66 KB
+DTS dist/index.d.ts  15.66 KB

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @objectstack/plugin-sharing
 
+## 6.9.0
+
+### Patch Changes
+
+- @objectstack/spec@6.9.0
+- @objectstack/core@6.9.0
+- @objectstack/objectql@6.9.0
+- @objectstack/platform-objects@6.9.0
+
 ## 6.8.1
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-export { SysRecordShare, SysSharingRule } from '@objectstack/platform-objects/security';
+export { SysRecordShare, SysShareLink, SysSharingRule } from '@objectstack/platform-objects/security';
 export { SysDepartment, SysDepartmentMember } from '@objectstack/platform-objects/identity';
-import { ISharingService, SharingExecutionContext, GrantShareInput, RecordShare, ISharingRuleService, DefineSharingRuleInput, SharingRuleRow, SharingRuleEvaluationResult, ITeamGraphService, IDepartmentGraphService } from '@objectstack/spec/contracts';
-export { DefineSharingRuleInput, GrantShareInput, IDepartmentGraphService, ISharingRuleService, ISharingService, ITeamGraphService, RecordShare, ShareAccessLevel, ShareRecipientType, ShareSource, SharingExecutionContext, SharingRuleEvaluationResult, SharingRuleRecipientType, SharingRuleRow } from '@objectstack/spec/contracts';
+import { ISharingService, SharingExecutionContext, GrantShareInput, RecordShare, ISharingRuleService, DefineSharingRuleInput, SharingRuleRow, SharingRuleEvaluationResult, IShareLinkService, CreateShareLinkInput, ShareLinkExecutionContext, ShareLink, ListShareLinksFilter, ResolveShareLinkResult, IHttpRequest, IHttpServer, ITeamGraphService, IDepartmentGraphService } from '@objectstack/spec/contracts';
+export { CreateShareLinkInput, DefineSharingRuleInput, GrantShareInput, IDepartmentGraphService, IShareLinkService, ISharingRuleService, ISharingService, ITeamGraphService, ListShareLinksFilter, RecordShare, ResolveShareLinkResult, SHARE_LINK_SERVICE, ShareAccessLevel, ShareLink, ShareLinkAudience, ShareLinkExecutionContext, ShareLinkPermission, ShareRecipientType, ShareSource, SharingExecutionContext, SharingRuleEvaluationResult, SharingRuleRecipientType, SharingRuleRow } from '@objectstack/spec/contracts';
 import { Plugin, PluginContext } from '@objectstack/core';
 import { EngineMiddleware } from '@objectstack/objectql';
 
@@ -98,6 +98,72 @@ declare class SharingRuleService implements ISharingRuleService {
     private purgeRuleGrants;
 }
 
+interface ShareLinkServiceOptions {
+    engine: SharingEngine;
+    /** Override the default SHA-256 hasher with argon2 / bcrypt for production. */
+    hashPassword?: (plain: string) => Promise<string>;
+    /** Companion verifier — must accept hashes produced by `hashPassword`. */
+    verifyPassword?: (plain: string, hash: string) => Promise<boolean>;
+    /**
+     * Bypass the per-object opt-in check (useful when the schema scan is
+     * happening after `start`). When omitted, calls against an object
+     * without `publicSharing.enabled=true` are rejected with 422.
+     */
+    permissive?: boolean;
+}
+/**
+ * Default `IShareLinkService` implementation.
+ *
+ * Persists every link in `sys_share_link`. The companion REST routes
+ * (`registerShareLinkRoutes`) thin-wrap the service; the public
+ * `/api/v1/share-links/:token` route resolves and re-injects the
+ * "share-link principal" into the execution context so the standard
+ * data middleware can authorise the downstream read.
+ */
+declare class ShareLinkService implements IShareLinkService {
+    private readonly engine;
+    private readonly permissive;
+    private readonly hashPassword;
+    private readonly verifyPassword;
+    constructor(opts: ShareLinkServiceOptions);
+    createLink(input: CreateShareLinkInput, context: ShareLinkExecutionContext): Promise<ShareLink>;
+    revokeLink(idOrToken: string, _context: ShareLinkExecutionContext): Promise<void>;
+    listLinks(filter: ListShareLinksFilter, context: ShareLinkExecutionContext): Promise<ShareLink[]>;
+    resolveToken(token: string, probe?: {
+        signedInUserId?: string;
+        recipientEmail?: string;
+        providedPassword?: string;
+    }): Promise<ResolveShareLinkResult | null>;
+}
+
+/**
+ * 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.
+ */
+
+interface ShareLinkRoutesOptions {
+    basePath?: string;
+    /** Read caller identity for authenticated routes. */
+    contextFromRequest?: (req: IHttpRequest) => ShareLinkExecutionContext;
+}
+declare function registerShareLinkRoutes(http: IHttpServer, service: ShareLinkService, engine: SharingEngine, opts?: ShareLinkRoutesOptions): void;
+
 type Cache = {
     expandUsers?: Map<string, string[]>;
     expandRole?: Map<string, string[]>;
@@ -237,6 +303,17 @@ interface SharingPluginOptions {
      * via env var without rebuilding.
      */
     enforce?: boolean;
+    /**
+     * Disable the public share-link REST routes. The `IShareLinkService`
+     * is always registered (other services may depend on it); only the
+     * HTTP surface is suppressed.
+     */
+    registerShareLinkRoutes?: boolean;
+    /**
+     * Base path for the share-link REST surface. Defaults to
+     * `/api/v1/share-links`.
+     */
+    shareLinkBasePath?: string;
 }
 /**
  * SharingServicePlugin — registers `sys_record_share`, the `sharing`
@@ -276,6 +353,7 @@ declare class SharingServicePlugin implements Plugin {
     private readonly options;
     private service?;
     private ruleService?;
+    private linkService?;
     constructor(options?: SharingPluginOptions);
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
@@ -287,4 +365,4 @@ declare class SharingServicePlugin implements Plugin {
  */
 declare function buildSharingMiddleware(service: SharingService): EngineMiddleware;
 
-export { type DepartmentGraphOptions, DepartmentGraphService, SHARING_RULE_HOOK_PACKAGE, type SharingEngine, type SharingPluginOptions, SharingRuleService, type SharingRuleServiceOptions, SharingService, type SharingServiceOptions, SharingServicePlugin, type TeamGraphOptions, TeamGraphService, bindRuleHooks, buildSharingMiddleware, expandPrincipal, unbindAllRuleHooks };
+export { type DepartmentGraphOptions, DepartmentGraphService, SHARING_RULE_HOOK_PACKAGE, type ShareLinkRoutesOptions, ShareLinkService, type ShareLinkServiceOptions, type SharingEngine, type SharingPluginOptions, SharingRuleService, type SharingRuleServiceOptions, SharingService, type SharingServiceOptions, SharingServicePlugin, type TeamGraphOptions, TeamGraphService, bindRuleHooks, buildSharingMiddleware, expandPrincipal, registerShareLinkRoutes, unbindAllRuleHooks };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { SysRecordShare, SysSharingRule } from '@objectstack/platform-objects/security';
+export { SysRecordShare, SysShareLink, SysSharingRule } from '@objectstack/platform-objects/security';
 export { SysDepartment, SysDepartmentMember } from '@objectstack/platform-objects/identity';
-import { ISharingService, SharingExecutionContext, GrantShareInput, RecordShare, ISharingRuleService, DefineSharingRuleInput, SharingRuleRow, SharingRuleEvaluationResult, ITeamGraphService, IDepartmentGraphService } from '@objectstack/spec/contracts';
-export { DefineSharingRuleInput, GrantShareInput, IDepartmentGraphService, ISharingRuleService, ISharingService, ITeamGraphService, RecordShare, ShareAccessLevel, ShareRecipientType, ShareSource, SharingExecutionContext, SharingRuleEvaluationResult, SharingRuleRecipientType, SharingRuleRow } from '@objectstack/spec/contracts';
+import { ISharingService, SharingExecutionContext, GrantShareInput, RecordShare, ISharingRuleService, DefineSharingRuleInput, SharingRuleRow, SharingRuleEvaluationResult, IShareLinkService, CreateShareLinkInput, ShareLinkExecutionContext, ShareLink, ListShareLinksFilter, ResolveShareLinkResult, IHttpRequest, IHttpServer, ITeamGraphService, IDepartmentGraphService } from '@objectstack/spec/contracts';
+export { CreateShareLinkInput, DefineSharingRuleInput, GrantShareInput, IDepartmentGraphService, IShareLinkService, ISharingRuleService, ISharingService, ITeamGraphService, ListShareLinksFilter, RecordShare, ResolveShareLinkResult, SHARE_LINK_SERVICE, ShareAccessLevel, ShareLink, ShareLinkAudience, ShareLinkExecutionContext, ShareLinkPermission, ShareRecipientType, ShareSource, SharingExecutionContext, SharingRuleEvaluationResult, SharingRuleRecipientType, SharingRuleRow } from '@objectstack/spec/contracts';
 import { Plugin, PluginContext } from '@objectstack/core';
 import { EngineMiddleware } from '@objectstack/objectql';
 
@@ -98,6 +98,72 @@ declare class SharingRuleService implements ISharingRuleService {
     private purgeRuleGrants;
 }
 
+interface ShareLinkServiceOptions {
+    engine: SharingEngine;
+    /** Override the default SHA-256 hasher with argon2 / bcrypt for production. */
+    hashPassword?: (plain: string) => Promise<string>;
+    /** Companion verifier — must accept hashes produced by `hashPassword`. */
+    verifyPassword?: (plain: string, hash: string) => Promise<boolean>;
+    /**
+     * Bypass the per-object opt-in check (useful when the schema scan is
+     * happening after `start`). When omitted, calls against an object
+     * without `publicSharing.enabled=true` are rejected with 422.
+     */
+    permissive?: boolean;
+}
+/**
+ * Default `IShareLinkService` implementation.
+ *
+ * Persists every link in `sys_share_link`. The companion REST routes
+ * (`registerShareLinkRoutes`) thin-wrap the service; the public
+ * `/api/v1/share-links/:token` route resolves and re-injects the
+ * "share-link principal" into the execution context so the standard
+ * data middleware can authorise the downstream read.
+ */
+declare class ShareLinkService implements IShareLinkService {
+    private readonly engine;
+    private readonly permissive;
+    private readonly hashPassword;
+    private readonly verifyPassword;
+    constructor(opts: ShareLinkServiceOptions);
+    createLink(input: CreateShareLinkInput, context: ShareLinkExecutionContext): Promise<ShareLink>;
+    revokeLink(idOrToken: string, _context: ShareLinkExecutionContext): Promise<void>;
+    listLinks(filter: ListShareLinksFilter, context: ShareLinkExecutionContext): Promise<ShareLink[]>;
+    resolveToken(token: string, probe?: {
+        signedInUserId?: string;
+        recipientEmail?: string;
+        providedPassword?: string;
+    }): Promise<ResolveShareLinkResult | null>;
+}
+
+/**
+ * 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.
+ */
+
+interface ShareLinkRoutesOptions {
+    basePath?: string;
+    /** Read caller identity for authenticated routes. */
+    contextFromRequest?: (req: IHttpRequest) => ShareLinkExecutionContext;
+}
+declare function registerShareLinkRoutes(http: IHttpServer, service: ShareLinkService, engine: SharingEngine, opts?: ShareLinkRoutesOptions): void;
+
 type Cache = {
     expandUsers?: Map<string, string[]>;
     expandRole?: Map<string, string[]>;
@@ -237,6 +303,17 @@ interface SharingPluginOptions {
      * via env var without rebuilding.
      */
     enforce?: boolean;
+    /**
+     * Disable the public share-link REST routes. The `IShareLinkService`
+     * is always registered (other services may depend on it); only the
+     * HTTP surface is suppressed.
+     */
+    registerShareLinkRoutes?: boolean;
+    /**
+     * Base path for the share-link REST surface. Defaults to
+     * `/api/v1/share-links`.
+     */
+    shareLinkBasePath?: string;
 }
 /**
  * SharingServicePlugin — registers `sys_record_share`, the `sharing`
@@ -276,6 +353,7 @@ declare class SharingServicePlugin implements Plugin {
     private readonly options;
     private service?;
     private ruleService?;
+    private linkService?;
     constructor(options?: SharingPluginOptions);
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
@@ -287,4 +365,4 @@ declare class SharingServicePlugin implements Plugin {
  */
 declare function buildSharingMiddleware(service: SharingService): EngineMiddleware;
 
-export { type DepartmentGraphOptions, DepartmentGraphService, SHARING_RULE_HOOK_PACKAGE, type SharingEngine, type SharingPluginOptions, SharingRuleService, type SharingRuleServiceOptions, SharingService, type SharingServiceOptions, SharingServicePlugin, type TeamGraphOptions, TeamGraphService, bindRuleHooks, buildSharingMiddleware, expandPrincipal, unbindAllRuleHooks };
+export { type DepartmentGraphOptions, DepartmentGraphService, SHARING_RULE_HOOK_PACKAGE, type ShareLinkRoutesOptions, ShareLinkService, type ShareLinkServiceOptions, type SharingEngine, type SharingPluginOptions, SharingRuleService, type SharingRuleServiceOptions, SharingService, type SharingServiceOptions, SharingServicePlugin, type TeamGraphOptions, TeamGraphService, bindRuleHooks, buildSharingMiddleware, expandPrincipal, registerShareLinkRoutes, unbindAllRuleHooks };