@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.11

package/dist/sharing/links/link-miss-throttle.js

@@ -0,0 +1,55 @@
+"use strict";
+// =============================================================================
+// LinkMissThrottle: the brute-force defence of public link resolution (#730)
+// =============================================================================
+//
+// A link token carries 256 bits of randomness, so guessing one is hopeless;
+// the throttle is about cost and noise: a client IP whose resolutions keep
+// failing (unknown, malformed, revoked, expired, wrong type) is refused with
+// 429 (`details.retryAfterMs`, `Retry-After`) once it reaches `maxMisses`
+// within `windowMs`, until its oldest miss leaves the window. A refused
+// request is not itself a miss, and a throttled address is refused even with
+// a valid token.
+//
+// The same bounded, in-process sliding window as `MemberLookupThrottle`,
+// keyed by the client address (`request.ip`, which honours the Fastify proxy
+// settings) instead of an account:
+//
+//   APPROXIMATE ACROSS REPLICAS, like the AI rate limits (docs/API.md): N
+//   replicas allow up to N times the limit.
+//   BOUNDED: at most `maxAccounts` addresses are tracked, oldest evicted.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LinkMissThrottle = void 0;
+const common_1 = require("@nestjs/common");
+const member_lookup_throttle_1 = require("../groups/member-lookup-throttle");
+/**
+ * Per-address throttle on failed public link resolutions. Configured by
+ * `SharingModule.forRoot({ links: { maxMissesPerIp } })` (default 30 per 10
+ * minutes); keys are client addresses.
+ *
+ * @stability experimental
+ */
+let LinkMissThrottle = class LinkMissThrottle extends member_lookup_throttle_1.MemberLookupThrottle {
+    /**
+     * @param options - the bounds; defaults 30 misses per 10 minutes, 10 000 addresses.
+     */
+    constructor(options = {}) {
+        super({ maxMisses: 30, windowMs: 10 * 60_000, maxAccounts: 10_000, ...options });
+    }
+};
+exports.LinkMissThrottle = LinkMissThrottle;
+exports.LinkMissThrottle = LinkMissThrottle = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object])
+], LinkMissThrottle);
+//# sourceMappingURL=link-miss-throttle.js.map

package/dist/sharing/links/link-miss-throttle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-miss-throttle.js","sourceRoot":"","sources":["../../../src/sharing/links/link-miss-throttle.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,6EAA6E;AAC7E,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,6EAA6E;AAC7E,0EAA0E;AAC1E,wEAAwE;AACxE,6EAA6E;AAC7E,iBAAiB;AACjB,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,mCAAmC;AACnC,EAAE;AACF,0EAA0E;AAC1E,4CAA4C;AAC5C,0EAA0E;AAC1E,gFAAgF;;;;;;;;;;;;AAEhF,2CAA4C;AAE5C,6EAA0G;AAE1G;;;;;;GAMG;AAEI,IAAM,gBAAgB,GAAtB,MAAM,gBAAiB,SAAQ,6CAAoB;IACxD;;OAEG;IACH,YAAY,UAAuC,EAAE;QACnD,KAAK,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,GAAG,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACnF,CAAC;CACF,CAAA;AAPY,4CAAgB;2BAAhB,gBAAgB;IAD5B,IAAA,mBAAU,GAAE;;GACA,gBAAgB,CAO5B"}

package/dist/sharing/links/link-token.d.ts

@@ -0,0 +1,11 @@
+/** The cipher domain prefix of a link token's ciphertext. */
+export declare const LINK_TOKEN_CIPHER_DOMAIN = "sharing.link:";
+/** A fresh token: `lnk_` and 43 base64url characters. */
+export declare function mintLinkToken(): string;
+/** Whether `value` is a well-formed token (checked before any lookup). */
+export declare function isLinkToken(value: unknown): value is string;
+/** The lookup hash of a token: SHA-256, hex. */
+export declare function hashLinkToken(token: string): string;
+/** The cipher domain of one link grant's token. */
+export declare function linkTokenPurpose(grantId: string): string;
+//# sourceMappingURL=link-token.d.ts.map

package/dist/sharing/links/link-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-token.d.ts","sourceRoot":"","sources":["../../../src/sharing/links/link-token.ts"],"names":[],"mappings":"AAyBA,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAExD,yDAAyD;AACzD,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE3D;AAED,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/sharing/links/link-token.js

@@ -0,0 +1,47 @@
+"use strict";
+// =============================================================================
+// Link-share tokens: minting, hashing, the cipher domain (issue #730). Internal.
+// =============================================================================
+//
+//   token       `lnk_` + base64url(32 random bytes): 47 characters. The prefix
+//               follows the `nod_` / `pat_` convention so secret scanning can
+//               recognise a leaked one.
+//   hash        SHA-256 hex of the whole token: the lookup key
+//               (`grants.link_token_hash`, unique), like a PAT's `tokenHash`.
+//   ciphertext  `encryptSecret(token, 'sharing.link:' + grantId)`: lets the
+//               grantor copy the link again. The grant id is chosen BEFORE the
+//               insert, so the cipher domain binds the row: a ciphertext copied
+//               onto another row fails authentication.
+//
+// None of these values is ever logged, put on a span, an audit row or an
+// error body.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINK_TOKEN_CIPHER_DOMAIN = void 0;
+exports.mintLinkToken = mintLinkToken;
+exports.isLinkToken = isLinkToken;
+exports.hashLinkToken = hashLinkToken;
+exports.linkTokenPurpose = linkTokenPurpose;
+const node_crypto_1 = require("node:crypto");
+const sharing_1 = require("@marinoscar/platform-contract/sharing");
+/** Random bytes in a token. */
+const TOKEN_BYTES = 32;
+/** The cipher domain prefix of a link token's ciphertext. */
+exports.LINK_TOKEN_CIPHER_DOMAIN = 'sharing.link:';
+/** A fresh token: `lnk_` and 43 base64url characters. */
+function mintLinkToken() {
+    return `${sharing_1.LINK_TOKEN_PREFIX}${(0, node_crypto_1.randomBytes)(TOKEN_BYTES).toString('base64url')}`;
+}
+/** Whether `value` is a well-formed token (checked before any lookup). */
+function isLinkToken(value) {
+    return typeof value === 'string' && sharing_1.LINK_TOKEN_PATTERN.test(value);
+}
+/** The lookup hash of a token: SHA-256, hex. */
+function hashLinkToken(token) {
+    return (0, node_crypto_1.createHash)('sha256').update(token, 'utf8').digest('hex');
+}
+/** The cipher domain of one link grant's token. */
+function linkTokenPurpose(grantId) {
+    return `${exports.LINK_TOKEN_CIPHER_DOMAIN}${grantId}`;
+}
+//# sourceMappingURL=link-token.js.map

package/dist/sharing/links/link-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-token.js","sourceRoot":"","sources":["../../../src/sharing/links/link-token.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,iFAAiF;AACjF,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,wCAAwC;AACxC,+DAA+D;AAC/D,8EAA8E;AAC9E,4EAA4E;AAC5E,+EAA+E;AAC/E,gFAAgF;AAChF,uDAAuD;AACvD,EAAE;AACF,yEAAyE;AACzE,cAAc;AACd,gFAAgF;;;AAahF,sCAEC;AAGD,kCAEC;AAGD,sCAEC;AAGD,4CAEC;AA5BD,6CAAsD;AAEtD,mEAA8F;AAE9F,+BAA+B;AAC/B,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB,6DAA6D;AAChD,QAAA,wBAAwB,GAAG,eAAe,CAAC;AAExD,yDAAyD;AACzD,SAAgB,aAAa;IAC3B,OAAO,GAAG,2BAAiB,GAAG,IAAA,yBAAW,EAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;AACjF,CAAC;AAED,0EAA0E;AAC1E,SAAgB,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,4BAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC;AAED,gDAAgD;AAChD,SAAgB,aAAa,CAAC,KAAa;IACzC,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED,mDAAmD;AACnD,SAAgB,gBAAgB,CAAC,OAAe;IAC9C,OAAO,GAAG,gCAAwB,GAAG,OAAO,EAAE,CAAC;AACjD,CAAC"}

package/dist/sharing/links/public-link.interceptor.d.ts

@@ -0,0 +1,34 @@
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
+import type { Observable } from 'rxjs';
+/**
+ * The headers every public link response carries.
+ *
+ * @stability experimental
+ */
+export declare const PUBLIC_LINK_RESPONSE_HEADERS: Readonly<Record<string, string>>;
+/**
+ * Sets {@link PUBLIC_LINK_RESPONSE_HEADERS} on a framework response.
+ *
+ * @param response - the Fastify reply (or a Node response).
+ *
+ * @stability experimental
+ */
+export declare function setPublicLinkHeaders(response: unknown): void;
+/**
+ * Sets `Cache-Control: no-store` and `Referrer-Policy: no-referrer` on the
+ * responses of a public link route.
+ *
+ * @example
+ * ```ts
+ * @UseGuards(LinkGrantGuard)
+ * @UseInterceptors(PublicLinkInterceptor)
+ * export class PublicMediaController { ... }
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare class PublicLinkInterceptor implements NestInterceptor {
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+//# sourceMappingURL=public-link.interceptor.d.ts.map

package/dist/sharing/links/public-link.interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-link.interceptor.d.ts","sourceRoot":"","sources":["../../../src/sharing/links/public-link.interceptor.ts"],"names":[],"mappings":"AAcA,OAAO,EAAc,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC3G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAEvC;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGxE,CAAC;AAQH;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAO5D;AAED;;;;;;;;;;;;;GAaG;AACH,qBACa,qBAAsB,YAAW,eAAe;IAC3D,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;CAI7E"}

package/dist/sharing/links/public-link.interceptor.js

@@ -0,0 +1,76 @@
+"use strict";
+// =============================================================================
+// PublicLinkInterceptor: the response headers of public link routes (#730)
+// =============================================================================
+//
+//   Cache-Control: no-store       a shared cache must never keep what a link
+//                                 showed: the link can be revoked a second later.
+//   Referrer-Policy: no-referrer  a page opened through a link never tells the
+//                                 next site where it came from.
+//
+// `LinkGrantGuard` sets the same headers before it decides, so a refusal (404,
+// 429) carries them too: guards run before interceptors. The interceptor
+// covers a public route an app guards by other means.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PublicLinkInterceptor = exports.PUBLIC_LINK_RESPONSE_HEADERS = void 0;
+exports.setPublicLinkHeaders = setPublicLinkHeaders;
+const common_1 = require("@nestjs/common");
+/**
+ * The headers every public link response carries.
+ *
+ * @stability experimental
+ */
+exports.PUBLIC_LINK_RESPONSE_HEADERS = Object.freeze({
+    'Cache-Control': 'no-store',
+    'Referrer-Policy': 'no-referrer',
+});
+/**
+ * Sets {@link PUBLIC_LINK_RESPONSE_HEADERS} on a framework response.
+ *
+ * @param response - the Fastify reply (or a Node response).
+ *
+ * @stability experimental
+ */
+function setPublicLinkHeaders(response) {
+    const sink = response;
+    if (!sink)
+        return;
+    for (const [name, value] of Object.entries(exports.PUBLIC_LINK_RESPONSE_HEADERS)) {
+        if (typeof sink.header === 'function')
+            sink.header(name, value);
+        else if (typeof sink.setHeader === 'function')
+            sink.setHeader(name, value);
+    }
+}
+/**
+ * Sets `Cache-Control: no-store` and `Referrer-Policy: no-referrer` on the
+ * responses of a public link route.
+ *
+ * @example
+ * ```ts
+ * @UseGuards(LinkGrantGuard)
+ * @UseInterceptors(PublicLinkInterceptor)
+ * export class PublicMediaController { ... }
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+let PublicLinkInterceptor = class PublicLinkInterceptor {
+    intercept(context, next) {
+        setPublicLinkHeaders(context.switchToHttp().getResponse());
+        return next.handle();
+    }
+};
+exports.PublicLinkInterceptor = PublicLinkInterceptor;
+exports.PublicLinkInterceptor = PublicLinkInterceptor = __decorate([
+    (0, common_1.Injectable)()
+], PublicLinkInterceptor);
+//# sourceMappingURL=public-link.interceptor.js.map

package/dist/sharing/links/public-link.interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-link.interceptor.js","sourceRoot":"","sources":["../../../src/sharing/links/public-link.interceptor.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,2EAA2E;AAC3E,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,kFAAkF;AAClF,+EAA+E;AAC/E,gEAAgE;AAChE,EAAE;AACF,+EAA+E;AAC/E,yEAAyE;AACzE,sDAAsD;AACtD,gFAAgF;;;;;;;;;AA4BhF,oDAOC;AAjCD,2CAA2G;AAG3G;;;;GAIG;AACU,QAAA,4BAA4B,GAAqC,MAAM,CAAC,MAAM,CAAC;IAC1F,eAAe,EAAE,UAAU;IAC3B,iBAAiB,EAAE,aAAa;CACjC,CAAC,CAAC;AAQH;;;;;;GAMG;AACH,SAAgB,oBAAoB,CAAC,QAAiB;IACpD,MAAM,IAAI,GAAG,QAA6B,CAAC;IAC3C,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,oCAA4B,CAAC,EAAE,CAAC;QACzE,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,UAAU;YAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;aAC3D,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,UAAU;YAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7E,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AAEI,IAAM,qBAAqB,GAA3B,MAAM,qBAAqB;IAChC,SAAS,CAAC,OAAyB,EAAE,IAAiB;QACpD,oBAAoB,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;IACvB,CAAC;CACF,CAAA;AALY,sDAAqB;gCAArB,qBAAqB;IADjC,IAAA,mBAAU,GAAE;GACA,qBAAqB,CAKjC"}

package/dist/sharing/links/public-links.controller.d.ts

@@ -0,0 +1,13 @@
+import { Type } from '@nestjs/common';
+/**
+ * Creates the `PublicLinksController` class, marked public with the host's
+ * `allowPublic` decorator. `SharingModule.forRoot()` calls it when the host
+ * provides one.
+ *
+ * @param allowPublic - the host's deliberate-public marker.
+ * @returns the controller class.
+ *
+ * @stability experimental
+ */
+export declare function createPublicLinksController(allowPublic: () => MethodDecorator & ClassDecorator): Type<unknown>;
+//# sourceMappingURL=public-links.controller.d.ts.map

package/dist/sharing/links/public-links.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-links.controller.d.ts","sourceRoot":"","sources":["../../../src/sharing/links/public-links.controller.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAmB,IAAI,EAA8B,MAAM,gBAAgB,CAAC;AAUnF;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,eAAe,GAAG,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,CAqC9G"}

package/dist/sharing/links/public-links.controller.js

@@ -0,0 +1,97 @@
+"use strict";
+// =============================================================================
+// The platform's public link route: GET /api/public/links/current (#730)
+// =============================================================================
+//
+// DELIBERATELY PUBLIC: no `@Auth()`. The caller is authenticated by the link
+// token in the `X-Link-Token` header (`LinkGrantGuard`), and the route carries
+// the app's `@Public()` marker through `host.access.allowPublic`, so the app's
+// route inventory sees it as public on purpose. Without that marker the
+// module leaves this route out (the guard and the pattern still work for an
+// app's own routes).
+//
+//   GET /public/links/current   X-Link-Token   200 resolution | 404 (generic) | 429
+//
+// The SPA's `/s` page reads the token from the URL fragment and calls this
+// route to learn what the link opens; app routes behind the same guard serve
+// the record itself.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPublicLinksController = createPublicLinksController;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const link_grants_dto_1 = require("../dto/link-grants.dto");
+const link_grant_decorators_1 = require("./link-grant.decorators");
+const link_grant_guard_1 = require("./link-grant.guard");
+const link_grants_service_1 = require("./link-grants.service");
+const public_link_interceptor_1 = require("./public-link.interceptor");
+/**
+ * Creates the `PublicLinksController` class, marked public with the host's
+ * `allowPublic` decorator. `SharingModule.forRoot()` calls it when the host
+ * provides one.
+ *
+ * @param allowPublic - the host's deliberate-public marker.
+ * @returns the controller class.
+ *
+ * @stability experimental
+ */
+function createPublicLinksController(allowPublic) {
+    let PublicLinksController = class PublicLinksController {
+        links;
+        constructor(links) {
+            this.links = links;
+        }
+        async current(link) {
+            return {
+                resourceType: link.resourceType,
+                resourceId: link.resourceId,
+                role: link.role,
+                expiresAt: link.expiresAt ? link.expiresAt.toISOString() : null,
+                title: await this.links.titleOf(link),
+            };
+        }
+    };
+    __decorate([
+        (0, common_1.Get)('current'),
+        (allowPublic()),
+        (0, link_grant_decorators_1.LinkGrantResource)(link_grants_service_1.ANY_LINK_RESOURCE_TYPE),
+        (0, swagger_1.ApiHeader)({ name: 'X-Link-Token', required: true, description: 'The link token, from the share URL fragment (`/s#lnk_...`). Never sent in a path or a query.' }),
+        (0, swagger_1.ApiOperation)({
+            summary: 'Resolve a share link',
+            description: 'Deliberately public: the `X-Link-Token` header is the only credential. Answers what the link opens (the ' +
+                "record's type, id and title, the role, the expiry). An unknown, malformed, revoked, expired or otherwise " +
+                'invalid token is the same 404 whatever the reason; a token in the path or the query string is never read. ' +
+                'Failed resolutions are limited per client address (default 30 per 10 minutes, approximate across replicas): ' +
+                'past it, 429 `LINK_RESOLUTION_THROTTLED` with `Retry-After`. Responses carry `Cache-Control: no-store` and ' +
+                '`Referrer-Policy: no-referrer`.',
+        }),
+        (0, swagger_1.ApiResponse)({ status: 200, type: link_grants_dto_1.PublicLinkResolutionResponseDto }),
+        (0, swagger_1.ApiResponse)({ status: 404, description: 'Link not found (every failure)' }),
+        (0, swagger_1.ApiResponse)({ status: 429, description: '`LINK_RESOLUTION_THROTTLED`' }),
+        __param(0, (0, link_grant_decorators_1.CurrentLinkGrant)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object]),
+        __metadata("design:returntype", Promise)
+    ], PublicLinksController.prototype, "current", null);
+    PublicLinksController = __decorate([
+        (0, swagger_1.ApiTags)('Grants'),
+        (0, common_1.Controller)('public/links'),
+        (0, common_1.UseGuards)(link_grant_guard_1.LinkGrantGuard),
+        (0, common_1.UseInterceptors)(public_link_interceptor_1.PublicLinkInterceptor),
+        __metadata("design:paramtypes", [link_grants_service_1.LinkGrantsService])
+    ], PublicLinksController);
+    return PublicLinksController;
+}
+//# sourceMappingURL=public-links.controller.js.map

package/dist/sharing/links/public-links.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-links.controller.js","sourceRoot":"","sources":["../../../src/sharing/links/public-links.controller.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,yEAAyE;AACzE,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,+EAA+E;AAC/E,wEAAwE;AACxE,4EAA4E;AAC5E,qBAAqB;AACrB,EAAE;AACF,oFAAoF;AACpF,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,qBAAqB;AACrB,gFAAgF;;;;;;;;;;;;;;AAsBhF,kEAqCC;AAzDD,2CAAmF;AACnF,6CAAgF;AAGhF,4DAAyE;AACzE,mEAA8E;AAC9E,yDAAoD;AACpD,+DAA0G;AAC1G,uEAAkE;AAElE;;;;;;;;;GASG;AACH,SAAgB,2BAA2B,CAAC,WAAmD;IAC7F,IAIM,qBAAqB,GAJ3B,MAIM,qBAAqB;QACI;QAA7B,YAA6B,KAAwB;YAAxB,UAAK,GAAL,KAAK,CAAmB;QAAG,CAAC;QAmBnD,AAAN,KAAK,CAAC,OAAO,CAAqB,IAAuB;YACvD,OAAO;gBACL,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI;gBAC/D,KAAK,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;aACtC,CAAC;QACJ,CAAC;KACF,CAAA;IATO;QAjBL,IAAA,YAAG,EAAC,SAAS,CAAC;QACd,CAAC,WAAW,EAAE,CAAC;QACf,IAAA,yCAAiB,EAAC,4CAAsB,CAAC;QACzC,IAAA,mBAAS,EAAC,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,8FAA8F,EAAE,CAAC;QAChK,IAAA,sBAAY,EAAC;YACZ,OAAO,EAAE,sBAAsB;YAC/B,WAAW,EACT,0GAA0G;gBAC1G,2GAA2G;gBAC3G,4GAA4G;gBAC5G,8GAA8G;gBAC9G,6GAA6G;gBAC7G,iCAAiC;SACpC,CAAC;QACD,IAAA,qBAAW,EAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,iDAA+B,EAAE,CAAC;QACnE,IAAA,qBAAW,EAAC,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,gCAAgC,EAAE,CAAC;QAC3E,IAAA,qBAAW,EAAC,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,6BAA6B,EAAE,CAAC;QAC1D,WAAA,IAAA,wCAAgB,GAAE,CAAA;;;;wDAQhC;IA5BG,qBAAqB;QAJ1B,IAAA,iBAAO,EAAC,QAAQ,CAAC;QACjB,IAAA,mBAAU,EAAC,cAAc,CAAC;QAC1B,IAAA,kBAAS,EAAC,iCAAc,CAAC;QACzB,IAAA,wBAAe,EAAC,+CAAqB,CAAC;yCAED,uCAAiB;OADjD,qBAAqB,CA6B1B;IAED,OAAO,qBAAqB,CAAC;AAC/B,CAAC"}

package/dist/sharing/metrics.d.ts

@@ -0,0 +1,75 @@
+import type { AppMetricDef } from '../otel-core/index';
+/**
+ * Every value of the `op` label of `app.sharing.group_mutations`.
+ *
+ * @stability experimental
+ */
+export declare const SHARING_MUTATION_OPS: readonly ["group_create", "group_update", "group_delete", "member_add", "member_remove", "member_role_change", "invite_create", "invite_revoke", "invite_accept", "invite_decline"];
+/**
+ * One of {@link SHARING_MUTATION_OPS}.
+ *
+ * @stability experimental
+ */
+export type SharingMutationOp = (typeof SHARING_MUTATION_OPS)[number];
+/**
+ * The code key of the counter, for `MetricsHostService.add`.
+ *
+ * @stability experimental
+ */
+export declare const SHARING_GROUP_MUTATIONS_METRIC = "sharingGroupMutations";
+/**
+ * The `outcome` label of `app.sharing.access_decisions` (#729): `rule_error`
+ * is a denial because an access rule failed or was misconfigured (a throw, an
+ * unknown verdict, a deny without `mayDeny`).
+ *
+ * @stability experimental
+ */
+export declare const SHARING_DECISION_OUTCOMES: readonly ["allowed", "denied", "rule_error"];
+/**
+ * The `via` label of `app.sharing.access_decisions`: what decided it, `app`
+ * for an access rule or an app grantee kind (the label stays a closed list: a
+ * rule id is not a metric dimension), or `none` for a denial (#729).
+ *
+ * @stability experimental
+ */
+export declare const SHARING_DECISION_VIAS: readonly ["owner", "group_owner", "user_grant", "group_grant", "org_default", "bypass", "app", "none"];
+/**
+ * The code key of the access-decision counter, for `MetricsHostService.add`.
+ *
+ * @stability experimental
+ */
+export declare const SHARING_ACCESS_DECISIONS_METRIC = "sharingAccessDecisions";
+/**
+ * The `outcome` label of `app.sharing.link_resolutions` (#730). A malformed
+ * or unknown token, a record that is gone and a role too weak for the route
+ * are all `not_found`.
+ *
+ * @stability experimental
+ */
+export declare const SHARING_LINK_RESOLUTION_OUTCOMES: readonly ["ok", "not_found", "expired", "revoked", "throttled", "wrong_type"];
+/**
+ * One of {@link SHARING_LINK_RESOLUTION_OUTCOMES}.
+ *
+ * @stability experimental
+ */
+export type SharingLinkResolutionOutcome = (typeof SHARING_LINK_RESOLUTION_OUTCOMES)[number];
+/**
+ * The code key of the link-resolution counter, for `MetricsHostService.add` (#730).
+ *
+ * @stability experimental
+ */
+export declare const SHARING_LINK_RESOLUTIONS_METRIC = "sharingLinkResolutions";
+/**
+ * The slice's metric declarations. Register them with the app's metric-name
+ * registry before the metrics host creates instruments.
+ *
+ * @example
+ * ```ts
+ * registerAppMetrics(SHARING_APP_METRICS);
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const SHARING_APP_METRICS: readonly AppMetricDef[];
+//# sourceMappingURL=metrics.d.ts.map

package/dist/sharing/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/sharing/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAmBvD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,qLAWvB,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,0BAA0B,CAAC;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,8CAA+C,CAAC;AAEtF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,wGAAyG,CAAC;AAE5I;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,2BAA2B,CAAC;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,+EAAgF,CAAC;AAE9H;;;;GAIG;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,OAAO,gCAAgC,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7F;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,2BAA2B,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,YAAY,EAoCtD,CAAC"}

package/dist/sharing/metrics.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHARING_APP_METRICS = exports.SHARING_LINK_RESOLUTIONS_METRIC = exports.SHARING_LINK_RESOLUTION_OUTCOMES = exports.SHARING_ACCESS_DECISIONS_METRIC = exports.SHARING_DECISION_VIAS = exports.SHARING_DECISION_OUTCOMES = exports.SHARING_GROUP_MUTATIONS_METRIC = exports.SHARING_MUTATION_OPS = void 0;
+// =============================================================================
+// Sharing metrics (issues #728 and #729)
+// =============================================================================
+//
+// Three counters, declared for the app's metric-name registry (the reference app
+// registers them in `common/otel/app-metric.manifest.ts`) and emitted through
+// `MetricsHostService.add`. Exported to Prometheus as
+// `app_sharing_group_mutations_total`, `app_sharing_access_decisions_total`
+// and `app_sharing_link_resolutions_total` (#730).
+//
+// BOUNDED LABELS ONLY: `op` from a closed list; `resource_type` (bounded by
+// the resource-type registry), `outcome` and `via` from closed lists. Never the
+// organization (an org id on a metric label is unbounded cardinality and a
+// tenant identifier in a shared store; it goes on the span as `org.id`), never
+// a group, user or record id.
+// =============================================================================
+/**
+ * Every value of the `op` label of `app.sharing.group_mutations`.
+ *
+ * @stability experimental
+ */
+exports.SHARING_MUTATION_OPS = [
+    'group_create',
+    'group_update',
+    'group_delete',
+    'member_add',
+    'member_remove',
+    'member_role_change',
+    'invite_create',
+    'invite_revoke',
+    'invite_accept',
+    'invite_decline',
+];
+/**
+ * The code key of the counter, for `MetricsHostService.add`.
+ *
+ * @stability experimental
+ */
+exports.SHARING_GROUP_MUTATIONS_METRIC = 'sharingGroupMutations';
+/**
+ * The `outcome` label of `app.sharing.access_decisions` (#729): `rule_error`
+ * is a denial because an access rule failed or was misconfigured (a throw, an
+ * unknown verdict, a deny without `mayDeny`).
+ *
+ * @stability experimental
+ */
+exports.SHARING_DECISION_OUTCOMES = ['allowed', 'denied', 'rule_error'];
+/**
+ * The `via` label of `app.sharing.access_decisions`: what decided it, `app`
+ * for an access rule or an app grantee kind (the label stays a closed list: a
+ * rule id is not a metric dimension), or `none` for a denial (#729).
+ *
+ * @stability experimental
+ */
+exports.SHARING_DECISION_VIAS = ['owner', 'group_owner', 'user_grant', 'group_grant', 'org_default', 'bypass', 'app', 'none'];
+/**
+ * The code key of the access-decision counter, for `MetricsHostService.add`.
+ *
+ * @stability experimental
+ */
+exports.SHARING_ACCESS_DECISIONS_METRIC = 'sharingAccessDecisions';
+/**
+ * The `outcome` label of `app.sharing.link_resolutions` (#730). A malformed
+ * or unknown token, a record that is gone and a role too weak for the route
+ * are all `not_found`.
+ *
+ * @stability experimental
+ */
+exports.SHARING_LINK_RESOLUTION_OUTCOMES = ['ok', 'not_found', 'expired', 'revoked', 'throttled', 'wrong_type'];
+/**
+ * The code key of the link-resolution counter, for `MetricsHostService.add` (#730).
+ *
+ * @stability experimental
+ */
+exports.SHARING_LINK_RESOLUTIONS_METRIC = 'sharingLinkResolutions';
+/**
+ * The slice's metric declarations. Register them with the app's metric-name
+ * registry before the metrics host creates instruments.
+ *
+ * @example
+ * ```ts
+ * registerAppMetrics(SHARING_APP_METRICS);
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+exports.SHARING_APP_METRICS = [
+    {
+        key: exports.SHARING_GROUP_MUTATIONS_METRIC,
+        name: 'app.sharing.group_mutations',
+        kind: 'counter',
+        unit: '{mutation}',
+        description: 'Committed changes to groups, their members and their invites, by operation.',
+        attributes: { op: { kind: 'enum', values: exports.SHARING_MUTATION_OPS } },
+    },
+    {
+        key: exports.SHARING_ACCESS_DECISIONS_METRIC,
+        name: 'app.sharing.access_decisions',
+        kind: 'counter',
+        unit: '{decision}',
+        description: 'AccessPolicy decisions on shareable records, by resource type, outcome and what decided them.',
+        // resource_type is bounded by the resource-type registry (only registered
+        // types reach a decision); never the organization or a record id.
+        attributes: {
+            resource_type: { kind: 'free' },
+            outcome: { kind: 'enum', values: exports.SHARING_DECISION_OUTCOMES },
+            via: { kind: 'enum', values: exports.SHARING_DECISION_VIAS },
+        },
+    },
+    {
+        key: exports.SHARING_LINK_RESOLUTIONS_METRIC,
+        name: 'app.sharing.link_resolutions',
+        kind: 'counter',
+        unit: '{resolution}',
+        description: 'Public link-share resolutions, by outcome and resource type. Resolutions are counted, never audited.',
+        // resource_type: the grant's registered type when one was found, else the
+        // route's declared type, else `none`; never a token, a hash or an address.
+        attributes: {
+            outcome: { kind: 'enum', values: exports.SHARING_LINK_RESOLUTION_OUTCOMES },
+            resource_type: { kind: 'free' },
+        },
+    },
+];
+//# sourceMappingURL=metrics.js.map

package/dist/sharing/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/sharing/metrics.ts"],"names":[],"mappings":";;;AAEA,gFAAgF;AAChF,yCAAyC;AACzC,gFAAgF;AAChF,EAAE;AACF,iFAAiF;AACjF,8EAA8E;AAC9E,sDAAsD;AACtD,4EAA4E;AAC5E,mDAAmD;AACnD,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,2EAA2E;AAC3E,+EAA+E;AAC/E,8BAA8B;AAC9B,gFAAgF;AAEhF;;;;GAIG;AACU,QAAA,oBAAoB,GAAG;IAClC,cAAc;IACd,cAAc;IACd,cAAc;IACd,YAAY;IACZ,eAAe;IACf,oBAAoB;IACpB,eAAe;IACf,eAAe;IACf,eAAe;IACf,gBAAgB;CACR,CAAC;AASX;;;;GAIG;AACU,QAAA,8BAA8B,GAAG,uBAAuB,CAAC;AAEtE;;;;;;GAMG;AACU,QAAA,yBAAyB,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE,YAAY,CAAU,CAAC;AAEtF;;;;;;GAMG;AACU,QAAA,qBAAqB,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAU,CAAC;AAE5I;;;;GAIG;AACU,QAAA,+BAA+B,GAAG,wBAAwB,CAAC;AAExE;;;;;;GAMG;AACU,QAAA,gCAAgC,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,CAAU,CAAC;AAS9H;;;;GAIG;AACU,QAAA,+BAA+B,GAAG,wBAAwB,CAAC;AAExE;;;;;;;;;;;GAWG;AACU,QAAA,mBAAmB,GAA4B;IAC1D;QACE,GAAG,EAAE,sCAA8B;QACnC,IAAI,EAAE,6BAA6B;QACnC,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,6EAA6E;QAC1F,UAAU,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,4BAAoB,EAAE,EAAE;KACnE;IACD;QACE,GAAG,EAAE,uCAA+B;QACpC,IAAI,EAAE,8BAA8B;QACpC,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,+FAA+F;QAC5G,0EAA0E;QAC1E,kEAAkE;QAClE,UAAU,EAAE;YACV,aAAa,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;YAC/B,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,iCAAyB,EAAE;YAC5D,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,6BAAqB,EAAE;SACrD;KACF;IACD;QACE,GAAG,EAAE,uCAA+B;QACpC,IAAI,EAAE,8BAA8B;QACpC,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,sGAAsG;QACnH,0EAA0E;QAC1E,2EAA2E;QAC3E,UAAU,EAAE;YACV,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,wCAAgC,EAAE;YACnE,aAAa,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;SAChC;KACF;CACF,CAAC"}