@adonis-agora/media 0.22.1 → 0.24.0

package/dist/src/index.js

@@ -2,6 +2,7 @@
 // `node ace configure` reaches the hook through this entry point, not through the package's
 // `./configure` export path.
 export { configure } from '../configure.js';
+export { adonisAuthIdentity, authorizers } from './access.js';
 export { Attachment, AttachmentManager, } from './attachment.js';
 // Real-content validation (magic-byte signatures behind `acceptsMimeTypes`)
 export { detectMimeType, isClosedSignatureWhitelist, isDetectableMimeType, SIGNATURE_HEAD_BYTES, verifyContentAgainstWhitelist, } from './content_type.js';
@@ -18,7 +19,7 @@ export { createDriveBackedResolver } from './disks/drive.js';
 // wiring presigned URLs outside the bundled disk)
 export { presignS3Url } from './disks/sigv4.js';
 // Errors
-export { ContentSignatureUnrecognizedError, ContentTypeMismatchError, ConversionArtifactMissingError, ConversionNotDefinedError, DeliverySignatureError, DirectUploadsNotConfiguredError, DriveNotReadyError, FfmpegFailedError, HlsSourceUnsupportedError, ImageProcessorMissingError, ImageSizeNotAllowedError, MediaNotFoundError, MediaObjectMissingError, MimeNotAllowedError, NotAnImageError, ResumableUploadsNotConfiguredError, StoreNotConfiguredError, TransformerConflictError, TransformerNotDefinedError, TransformerOutputError, TransformerRuntimeMissingError, TransformNotReadyError, UnsafeFileNameError, UploadNotSupportedError, UploadOffsetConflictError, UploadPartOutOfRangeError, UploadPartSizeError, UploadPartsIncompleteError, UploadSessionExpiredError, UploadSessionNotFoundError, UploadSessionStoreNotConfiguredError, VariantNotFoundError, } from './errors.js';
+export { ContentSignatureUnrecognizedError, ContentTypeMismatchError, ConversionArtifactMissingError, ConversionNotDefinedError, DeliverySignatureError, DirectUploadsNotConfiguredError, DriveNotReadyError, FfmpegFailedError, HlsSourceUnsupportedError, ImageProcessorMissingError, ImageSizeNotAllowedError, MediaAccessDeniedError, MediaNotFoundError, MediaObjectMissingError, MimeNotAllowedError, NotAnImageError, ResumableUploadsNotConfiguredError, StoreNotConfiguredError, TransformerConflictError, TransformerNotDefinedError, TransformerOutputError, TransformerRuntimeMissingError, TransformNotReadyError, UnsafeFileNameError, UploadNotSupportedError, UploadOffsetConflictError, UploadPartOutOfRangeError, UploadPartSizeError, UploadPartsIncompleteError, UploadSessionExpiredError, UploadSessionNotFoundError, UploadSessionStoreNotConfiguredError, VariantNotFoundError, } from './errors.js';
 export { isExtendedDisk } from './extended_disk.js';
 // Validates a client-supplied upload file name before it reaches a storage key; the same guard the
 // built-in `keyFor` defaults and `MediaLibrary#layoutPath` run every file name through.
@@ -26,6 +27,7 @@ export { sanitizeFileName } from './file_name.js';
 export { HlsDeliveryHandler } from './hls/delivery.js';
 // HLS delivery (playlist rewriting + the framework-agnostic package handler)
 export { classifyUri, HLS_PLAYLIST_CONTENT_TYPE, HLS_SEGMENT_CONTENT_TYPE, hlsArtifactContentType, isRelativeUri, resolvePackagePath, rewriteHlsPlaylist, } from './hls/playlist.js';
+export { MediaAccess } from './media_access.js';
 export { MediaCollectionRegistry } from './media_collection.js';
 export { MediaLibrary } from './media_library.js';
 // Manager + layers

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/integrations/authkit.d.ts

@@ -0,0 +1,57 @@
+import type { MediaIdentityResolver } from '../access.js';
+/**
+ * The bits of `@adonis-agora/authkit-server` this integration uses — typed structurally so the
+ * media package carries no dependency on it.
+ */
+interface AuthkitServerModule {
+    getAccountId(ctx: unknown): string | null;
+    realAccountId(ctx: unknown): string | null;
+}
+/** The bits of `@adonis-agora/authkit-client` this integration uses. */
+interface AuthkitClientModule {
+    getAuthkit(ctx: unknown): Promise<{
+        getIdentity(): Promise<{
+            userId: string;
+            globalRoles?: string[];
+            orgId?: string | null;
+        } | null>;
+    }>;
+}
+export interface AuthkitIdentityOptions {
+    /**
+     * Which side of authkit this app is:
+     * - `'server'` — the app IS the identity provider (`@adonis-agora/authkit-server`): the account
+     *   comes from the console session (`getAccountId`, impersonation-aware; `realAccountId` for
+     *   permission checks);
+     * - `'client'` — the app signs in against one (`@adonis-agora/authkit-client`): the identity
+     *   comes from `ctx.authkit` (`getAuthkit(ctx).getIdentity()`), with its global roles and active
+     *   organization;
+     * - `'auto'` (default) — the client when the request carries `ctx.authkit`, the server when its
+     *   package is installed, the client otherwise.
+     */
+    side?: 'auto' | 'server' | 'client';
+    /** Subject type handed to authz. Default `'user'`. */
+    type?: string;
+    /** @internal test seams: how the authkit packages are loaded. */
+    load?: {
+        server?: () => Promise<AuthkitServerModule>;
+        client?: () => Promise<AuthkitClientModule>;
+    };
+}
+/**
+ * `access.identity` for apps on authkit — who the current user is, as authkit sees them:
+ *
+ * ```ts
+ * // config/media.ts
+ * import { authkitIdentity } from '@adonis-agora/media/authkit'
+ * export default defineConfig({ access: { identity: authkitIdentity() } })
+ * ```
+ *
+ * On the server side, `id` is the account the request acts as (an impersonating admin sees the
+ * user's files) and `realId` the human behind it (what `@adonis-agora/media/authz` checks
+ * permissions for). On the client side both are the token's `sub`, with its global roles and
+ * active organization as `roles` / `tenantId`.
+ */
+export declare function authkitIdentity(options?: AuthkitIdentityOptions): MediaIdentityResolver;
+export {};
+//# sourceMappingURL=authkit.d.ts.map

package/dist/src/integrations/authkit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authkit.d.ts","sourceRoot":"","sources":["../../../src/integrations/authkit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAgB,MAAM,cAAc,CAAC;AAExE;;;GAGG;AACH,UAAU,mBAAmB;IAC3B,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1C,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED,wEAAwE;AACxE,UAAU,mBAAmB;IAC3B,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;QAChC,WAAW,IAAI,OAAO,CAAC;YACrB,MAAM,EAAE,MAAM,CAAC;YACf,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;YACvB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;SACvB,GAAG,IAAI,CAAC,CAAC;KACX,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpC,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAC5C,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;KAC7C,CAAC;CACH;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,qBAAqB,CA+C3F"}

package/dist/src/integrations/authkit.js

@@ -0,0 +1,71 @@
+const importServer = () => import('@adonis-agora/authkit-server');
+const importClient = () => import('@adonis-agora/authkit-client');
+/**
+ * `access.identity` for apps on authkit — who the current user is, as authkit sees them:
+ *
+ * ```ts
+ * // config/media.ts
+ * import { authkitIdentity } from '@adonis-agora/media/authkit'
+ * export default defineConfig({ access: { identity: authkitIdentity() } })
+ * ```
+ *
+ * On the server side, `id` is the account the request acts as (an impersonating admin sees the
+ * user's files) and `realId` the human behind it (what `@adonis-agora/media/authz` checks
+ * permissions for). On the client side both are the token's `sub`, with its global roles and
+ * active organization as `roles` / `tenantId`.
+ */
+export function authkitIdentity(options = {}) {
+    const side = options.side ?? 'auto';
+    const type = options.type;
+    const loadServer = options.load?.server ?? importServer;
+    const loadClient = options.load?.client ?? importClient;
+    const fromServer = async (ctx) => {
+        const server = await loadServer();
+        const id = server.getAccountId(ctx);
+        if (!id)
+            return null;
+        return { id, realId: server.realAccountId(ctx) ?? id, ...(type ? { type } : {}) };
+    };
+    const fromClient = async (ctx) => {
+        const client = await loadClient();
+        const identity = await (await client.getAuthkit(ctx)).getIdentity();
+        if (!identity)
+            return null;
+        return {
+            id: identity.userId,
+            realId: identity.userId,
+            roles: identity.globalRoles ?? [],
+            tenantId: identity.orgId ?? null,
+            ...(type ? { type } : {}),
+        };
+    };
+    return async (ctx) => {
+        if (side === 'server')
+            return fromServer(ctx);
+        if (side === 'client')
+            return fromClient(ctx);
+        if (ctx.authkit)
+            return fromClient(ctx);
+        try {
+            return await fromServer(ctx);
+        }
+        catch (error) {
+            if (!isModuleNotFound(error))
+                throw error;
+        }
+        try {
+            return await fromClient(ctx);
+        }
+        catch (error) {
+            if (!isModuleNotFound(error))
+                throw error;
+            throw new Error("authkitIdentity() needs '@adonis-agora/authkit-server' (an identity-provider app) or " +
+                "'@adonis-agora/authkit-client' (an app signing in against one), and neither is " +
+                'installed. Install the one this app uses, or set `access.identity` to another resolver.', { cause: error });
+        }
+    };
+}
+function isModuleNotFound(error) {
+    return error?.code === 'ERR_MODULE_NOT_FOUND';
+}
+//# sourceMappingURL=authkit.js.map

package/dist/src/integrations/authkit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authkit.js","sourceRoot":"","sources":["../../../src/integrations/authkit.ts"],"names":[],"mappings":"AA4CA,MAAM,YAAY,GAAG,GAAG,EAAE,CACxB,MAAM,CAAC,8BAAwC,CAAiC,CAAC;AACnF,MAAM,YAAY,GAAG,GAAG,EAAE,CACxB,MAAM,CAAC,8BAAwC,CAAiC,CAAC;AAEnF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,OAAO,GAA2B,EAAE;IAClE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1B,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,MAAM,IAAI,YAAY,CAAC;IACxD,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,MAAM,IAAI,YAAY,CAAC;IAExD,MAAM,UAAU,GAAG,KAAK,EAAE,GAAY,EAAgC,EAAE;QACtE,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;QAClC,MAAM,EAAE,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACrB,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACpF,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,KAAK,EAAE,GAAY,EAAgC,EAAE;QACtE,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACpE,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC3B,OAAO;YACL,EAAE,EAAE,QAAQ,CAAC,MAAM;YACnB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,KAAK,EAAE,QAAQ,CAAC,WAAW,IAAI,EAAE;YACjC,QAAQ,EAAE,QAAQ,CAAC,KAAK,IAAI,IAAI;YAChC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1B,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE;QACnB,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAK,GAA6B,CAAC,OAAO;YAAE,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;QACnE,IAAI,CAAC;YACH,OAAO,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;QAC5C,CAAC;QACD,IAAI,CAAC;YACH,OAAO,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YAC1C,MAAM,IAAI,KAAK,CACb,uFAAuF;gBACrF,iFAAiF;gBACjF,yFAAyF,EAC3F,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAQ,KAA2B,EAAE,IAAI,KAAK,sBAAsB,CAAC;AACvE,CAAC"}

package/dist/src/integrations/authz.d.ts

@@ -0,0 +1,36 @@
+import type { MediaAccessRequest, MediaAuthorizer } from '../access.js';
+/** The bits of `@adonis-agora/authz`'s service this integration uses (typed structurally). */
+interface AuthzService {
+    can(user: unknown, permission: string, options?: {
+        scope?: unknown;
+    }): Promise<boolean>;
+    hasAnyRole(user: unknown, roles: string[], options?: {
+        scope?: unknown;
+    }): Promise<boolean>;
+}
+export interface AuthzRuleOptions {
+    /** Explicit authz tenant scope for the check. Default: authz's own resolvers (`resolveTenant`). */
+    scope?: (request: MediaAccessRequest) => unknown;
+    /** @internal test seam: how the authz service is loaded. */
+    load?: () => Promise<AuthzService>;
+}
+/**
+ * Media authorizers backed by `@adonis-agora/authz` (an optional peer, loaded on first use).
+ * Wildcards, roles → permissions, super-admins and tenancy all apply, as in any authz check.
+ *
+ * ```ts
+ * import { authorizers } from '@adonis-agora/media'
+ * import { authz } from '@adonis-agora/media/authz'
+ *
+ * { name: 'prescription', access: { read: authorizers.any(authorizers.owner(), authz.can('prescriptions.read')) } }
+ * { name: 'reports', access: { read: authz.can(({ collection, action }) => `media.${collection}.${action}`) } }
+ * ```
+ */
+export declare const authz: {
+    /** The user holds `permission` (a string, or derived from the request). Anonymous ⇒ no. */
+    can(permission: string | ((request: MediaAccessRequest) => string), options?: AuthzRuleOptions): MediaAuthorizer;
+    /** The user has any of these roles in authz (store roles, `resolveRoles`, token roles). */
+    roles(roles: readonly string[], options?: AuthzRuleOptions): MediaAuthorizer;
+};
+export {};
+//# sourceMappingURL=authz.d.ts.map

package/dist/src/integrations/authz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz.d.ts","sourceRoot":"","sources":["../../../src/integrations/authz.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAgB,MAAM,cAAc,CAAC;AAEtF,8FAA8F;AAC9F,UAAU,YAAY;IACpB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxF,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7F;AAED,MAAM,WAAW,gBAAgB;IAC/B,mGAAmG;IACnG,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;CACpC;AAiBD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK;IAChB,2FAA2F;IAC3F,GAAG,aACW,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,kBAAkB,KAAK,MAAM,CAAC,YACrD,gBAAgB,GACxB,eAAe;IAWlB,2FAA2F;IAC3F,KAAK,QAAQ,SAAS,MAAM,EAAE,YAAW,gBAAgB,GAAQ,eAAe;CAajF,CAAC"}

package/dist/src/integrations/authz.js

@@ -0,0 +1,51 @@
+const importAuthz = async () => (await import('@adonis-agora/authz/services/main'))
+    .default;
+/**
+ * What authz is asked about: the app's own user object when the identity has one (so a custom
+ * `resolveSubjectRef` keeps working), otherwise the `{ type, id }` reference of the human behind
+ * the request — `realId`, never the impersonated account: an admin acting as someone must not
+ * gain that someone's permissions, nor lose their own.
+ */
+function authzSubject(subject) {
+    if (subject.user != null)
+        return subject.user;
+    return { type: subject.type ?? 'user', id: subject.realId ?? subject.id };
+}
+/**
+ * Media authorizers backed by `@adonis-agora/authz` (an optional peer, loaded on first use).
+ * Wildcards, roles → permissions, super-admins and tenancy all apply, as in any authz check.
+ *
+ * ```ts
+ * import { authorizers } from '@adonis-agora/media'
+ * import { authz } from '@adonis-agora/media/authz'
+ *
+ * { name: 'prescription', access: { read: authorizers.any(authorizers.owner(), authz.can('prescriptions.read')) } }
+ * { name: 'reports', access: { read: authz.can(({ collection, action }) => `media.${collection}.${action}`) } }
+ * ```
+ */
+export const authz = {
+    /** The user holds `permission` (a string, or derived from the request). Anonymous ⇒ no. */
+    can(permission, options = {}) {
+        const load = options.load ?? importAuthz;
+        return async (request) => {
+            if (!request.subject)
+                return false;
+            const service = await load();
+            const name = typeof permission === 'function' ? permission(request) : permission;
+            const scope = options.scope?.(request);
+            return service.can(authzSubject(request.subject), name, scope !== undefined ? { scope } : {});
+        };
+    },
+    /** The user has any of these roles in authz (store roles, `resolveRoles`, token roles). */
+    roles(roles, options = {}) {
+        const load = options.load ?? importAuthz;
+        return async (request) => {
+            if (!request.subject)
+                return false;
+            const service = await load();
+            const scope = options.scope?.(request);
+            return service.hasAnyRole(authzSubject(request.subject), [...roles], scope !== undefined ? { scope } : {});
+        };
+    },
+};
+//# sourceMappingURL=authz.js.map

package/dist/src/integrations/authz.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz.js","sourceRoot":"","sources":["../../../src/integrations/authz.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,GAAG,KAAK,IAA2B,EAAE,CACnD,CAAC,MAAM,MAAM,CAAC,mCAA6C,CAAC,CAA+B;KACzF,OAAO,CAAC;AAEb;;;;;GAKG;AACH,SAAS,YAAY,CAAC,OAAqB;IACzC,IAAI,OAAO,CAAC,IAAI,IAAI,IAAI;QAAE,OAAO,OAAO,CAAC,IAAI,CAAC;IAC9C,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,MAAM,EAAE,EAAE,EAAE,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,2FAA2F;IAC3F,GAAG,CACD,UAA8D,EAC9D,OAAO,GAAqB,EAAE;QAE9B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;QACzC,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;YACvB,IAAI,CAAC,OAAO,CAAC,OAAO;gBAAE,OAAO,KAAK,CAAC;YACnC,MAAM,OAAO,GAAG,MAAM,IAAI,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,OAAO,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;YACjF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,CAAC;YACvC,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChG,CAAC,CAAC;IACJ,CAAC;IAED,2FAA2F;IAC3F,KAAK,CAAC,KAAwB,EAAE,OAAO,GAAqB,EAAE;QAC5D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;QACzC,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;YACvB,IAAI,CAAC,OAAO,CAAC,OAAO;gBAAE,OAAO,KAAK,CAAC;YACnC,MAAM,OAAO,GAAG,MAAM,IAAI,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,CAAC;YACvC,OAAO,OAAO,CAAC,UAAU,CACvB,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,EAC7B,CAAC,GAAG,KAAK,CAAC,EACV,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CACrC,CAAC;QACJ,CAAC,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/src/media_access.d.ts

@@ -0,0 +1,126 @@
+import type { Readable } from 'node:stream';
+import { type MediaAction, type MediaAuthorizer, type MediaIdentityResolver, type MediaSubject } from './access.js';
+import type { DeliveryMode } from './delivery.js';
+import type { MediaLibrary } from './media_library.js';
+import type { MediaRecord } from './media_record.js';
+import type { ResponsiveImage, ResponsiveImageOptions } from './responsive_image.js';
+/**
+ * The slice of an AdonisJS `HttpContext` the delivery route uses — typed structurally so the
+ * route works with the real context and with a test double alike.
+ */
+export interface DeliveryRouteContext {
+    params: Record<string, unknown>;
+    request: {
+        qs(): Record<string, unknown>;
+        header(name: string): string | undefined | null;
+    };
+    response: {
+        status(code: number): {
+            json(body: unknown): unknown;
+        } | unknown;
+        header(name: string, value: string): unknown;
+        redirect(url: string): unknown;
+        stream(stream: Readable): unknown;
+    };
+}
+export interface MediaDeliveryRouteOptions {
+    /**
+     * Who may read. Default: the record's collection `access.read`. With neither, every request is
+     * refused — the route never serves by default.
+     */
+    authorize?: MediaAuthorizer;
+    /** Route parameter holding the media id. Default `'id'`. */
+    param?: string;
+    /**
+     * `Cache-Control` for what the route serves. Default `'private, max-age=60'`: a personal file
+     * must not be kept by a shared cache, and a minute absorbs a page rendering it many times.
+     */
+    cacheControl?: string;
+    /** Override `delivery.mode` for this route. */
+    mode?: DeliveryMode;
+    /** Signed-URL lifetime when the resolved mode is `signed`. */
+    signedTtlSeconds?: number;
+}
+/**
+ * Authorization for media, wired to the app's identity (`access.identity` — authkit, AdonisJS
+ * auth or your own) and the collections' `access` policies. `media.access` on the manager.
+ *
+ * The library still never decides authorization by itself: every rule comes from the app —
+ * a collection's `access`, or an `authorize` passed in. This is the plumbing that applies them.
+ */
+export declare class MediaAccess {
+    #private;
+    constructor(options: {
+        library: MediaLibrary;
+        identity?: MediaIdentityResolver | undefined;
+    });
+    /** The current user per the configured identity resolver, or `null`. */
+    subject(ctx: unknown): Promise<MediaSubject | null>;
+    /**
+     * May the current user perform `action`? `target` is the record (read) or the collection a file
+     * is going into (write). The rule is `authorize` when given, otherwise the collection's
+     * `access[action]`; neither ⇒ `false`.
+     */
+    can(ctx: unknown, action: MediaAction, target: MediaRecord | {
+        collection: string;
+    }, authorize?: MediaAuthorizer): Promise<boolean>;
+    /**
+     * {@link can}, throwing {@link MediaAccessDeniedError} when refused — `401` for an anonymous
+     * request, `403` otherwise. Use it in your own controllers and upload policies:
+     *
+     * ```ts
+     * // DirectUploadPolicy.onInitiate
+     * await media.access.authorize(ctx, 'write', { collection: 'avatar' })
+     * ```
+     */
+    authorize(ctx: unknown, action: MediaAction, target: MediaRecord | {
+        collection: string;
+    }, authorize?: MediaAuthorizer): Promise<void>;
+    /**
+     * `media.library.image(id)` for the current user: checks read access first (the collection's
+     * `access.read`, or `authorize`), so the URLs it hands out — signed ones especially, which
+     * carry their authorization — only ever reach someone allowed to see the file.
+     */
+    image(ctx: unknown, id: string, options?: ResponsiveImageOptions & {
+        authorize?: MediaAuthorizer;
+    }): Promise<ResponsiveImage>;
+    /**
+     * Authorize and answer one media read — the core of {@link deliveryRoute}, for a controller that
+     * finds the record its own way (a stable `/profiles/:id/photo` URL, a record looked up by its
+     * owner):
+     *
+     * ```ts
+     * async show(ctx) {
+     *   const [avatar] = await media.library.list('User', ctx.params.id, 'avatar')
+     *   return media.access.serve(ctx, avatar, { authorize: canSeeProfile })
+     * }
+     * ```
+     *
+     * `target` is the record, its id, or `null`/`undefined` (answered 404). Everything else is as in
+     * {@link deliveryRoute}: the read is authorized unless the URL carries a valid signature, the query
+     * (`?conversion`, `?w`, `?q`, `?exp`, `?sig`) and `Accept` are honoured, the file is redirected or
+     * streamed with its headers, and the library's errors are answered as HTTP.
+     */
+    serve(ctx: DeliveryRouteContext, target: MediaRecord | string | null | undefined, options?: Omit<MediaDeliveryRouteOptions, 'param'>): Promise<unknown>;
+    /**
+     * A ready AdonisJS route handler that serves a media record — the delivery route every app was
+     * hand-writing:
+     *
+     * ```ts
+     * const serveMedia = media.access.deliveryRoute({ authorize: authorizers.owner() })
+     * router.get('/media/:id', serveMedia)
+     * ```
+     *
+     * - authorizes the read (`authorize`, or the collection's `access.read`; neither ⇒ refused),
+     *   unless the URL carries a valid `delivery.signing` signature — that signature IS the
+     *   authorization the app made when it issued the URL;
+     * - passes `?conversion`, `?w`, `?q`, `Accept`, `?exp`, `?sig` through (on-demand resize,
+     *   format negotiation, signed URLs);
+     * - redirects or streams per `delivery.mode`, with `Content-Type`, `Content-Length`,
+     *   `Content-Disposition: inline`, `Cache-Control` (private by default) and `Vary: Accept`;
+     * - answers the library's errors as HTTP: 404 (unknown record or conversion), 400 (size not
+     *   allowed, not an image), 401/403 (not signed in / not allowed / bad signature).
+     */
+    deliveryRoute(options?: MediaDeliveryRouteOptions): (ctx: DeliveryRouteContext) => Promise<unknown>;
+}
+//# sourceMappingURL=media_access.d.ts.map

package/dist/src/media_access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media_access.d.ts","sourceRoot":"","sources":["../../src/media_access.ts"],"names":[],"mappings":"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"}

package/dist/src/media_access.js

@@ -0,0 +1,197 @@
+import { adonisAuthIdentity, toAuthorizer, } from './access.js';
+import { ConversionNotDefinedError, DeliverySignatureError, ImageSizeNotAllowedError, MediaAccessDeniedError, MediaNotFoundError, NotAnImageError, TransformNotReadyError, } from './errors.js';
+/**
+ * Authorization for media, wired to the app's identity (`access.identity` — authkit, AdonisJS
+ * auth or your own) and the collections' `access` policies. `media.access` on the manager.
+ *
+ * The library still never decides authorization by itself: every rule comes from the app —
+ * a collection's `access`, or an `authorize` passed in. This is the plumbing that applies them.
+ */
+export class MediaAccess {
+    #library;
+    #identity;
+    constructor(options) {
+        this.#library = options.library;
+        this.#identity = options.identity ?? adonisAuthIdentity;
+    }
+    /** The current user per the configured identity resolver, or `null`. */
+    async subject(ctx) {
+        return (await this.#identity(ctx)) ?? null;
+    }
+    /**
+     * May the current user perform `action`? `target` is the record (read) or the collection a file
+     * is going into (write). The rule is `authorize` when given, otherwise the collection's
+     * `access[action]`; neither ⇒ `false`.
+     */
+    async can(ctx, action, target, authorize) {
+        return (await this.#decide(ctx, action, target, authorize)).allowed;
+    }
+    /** Resolve the subject ONCE and run the rule — so a denial's 401/403 matches what the rule saw. */
+    async #decide(ctx, action, target, authorize) {
+        const collection = target.collection;
+        const record = 'id' in target ? target : undefined;
+        const rule = authorize ?? toAuthorizer(this.#library.collections.get(collection).access?.[action]);
+        const subject = await this.subject(ctx);
+        return { allowed: await rule({ ctx, action, collection, record, subject }), subject };
+    }
+    /**
+     * {@link can}, throwing {@link MediaAccessDeniedError} when refused — `401` for an anonymous
+     * request, `403` otherwise. Use it in your own controllers and upload policies:
+     *
+     * ```ts
+     * // DirectUploadPolicy.onInitiate
+     * await media.access.authorize(ctx, 'write', { collection: 'avatar' })
+     * ```
+     */
+    async authorize(ctx, action, target, authorize) {
+        const { allowed, subject } = await this.#decide(ctx, action, target, authorize);
+        if (allowed)
+            return;
+        throw new MediaAccessDeniedError(action, target.collection, 'id' in target ? target.id : undefined, subject === null);
+    }
+    /**
+     * `media.library.image(id)` for the current user: checks read access first (the collection's
+     * `access.read`, or `authorize`), so the URLs it hands out — signed ones especially, which
+     * carry their authorization — only ever reach someone allowed to see the file.
+     */
+    async image(ctx, id, options = {}) {
+        const { authorize, ...imageOptions } = options;
+        const record = await this.#library.find(id);
+        if (!record)
+            throw new MediaNotFoundError(id);
+        await this.authorize(ctx, 'read', record, authorize);
+        return this.#library.image(id, imageOptions);
+    }
+    /**
+     * Authorize and answer one media read — the core of {@link deliveryRoute}, for a controller that
+     * finds the record its own way (a stable `/profiles/:id/photo` URL, a record looked up by its
+     * owner):
+     *
+     * ```ts
+     * async show(ctx) {
+     *   const [avatar] = await media.library.list('User', ctx.params.id, 'avatar')
+     *   return media.access.serve(ctx, avatar, { authorize: canSeeProfile })
+     * }
+     * ```
+     *
+     * `target` is the record, its id, or `null`/`undefined` (answered 404). Everything else is as in
+     * {@link deliveryRoute}: the read is authorized unless the URL carries a valid signature, the query
+     * (`?conversion`, `?w`, `?q`, `?exp`, `?sig`) and `Accept` are honoured, the file is redirected or
+     * streamed with its headers, and the library's errors are answered as HTTP.
+     */
+    async serve(ctx, target, options = {}) {
+        const { request, response } = ctx;
+        const cacheControl = options.cacheControl ?? 'private, max-age=60';
+        try {
+            const record = typeof target === 'string' ? await this.#library.find(target) : (target ?? null);
+            if (!record)
+                throw new MediaNotFoundError(typeof target === 'string' ? target : '');
+            const id = record.id;
+            const qs = request.qs();
+            const signed = {
+                mediaId: id,
+                conversion: stringParam(qs.conversion),
+                width: stringParam(qs.w),
+                quality: stringParam(qs.q),
+                expires: stringParam(qs.exp),
+                signature: stringParam(qs.sig),
+            };
+            // A valid signature is a prior authorization; an invalid or expired one is refused
+            // (DeliverySignatureError). Unsigned requests are this caller's to authorize.
+            const trusted = this.#library.checkDeliverySignature(signed, { required: false });
+            if (!trusted)
+                await this.authorize(ctx, 'read', record, options.authorize);
+            const result = await this.#library.deliver(id, {
+                ...(signed.conversion !== undefined ? { conversion: signed.conversion } : {}),
+                ...(signed.width !== undefined && signed.width !== ''
+                    ? {
+                        width: signed.width,
+                        quality: signed.quality,
+                        accept: request.header('accept') ?? undefined,
+                    }
+                    : {}),
+                ...(trusted ? { trusted: true } : {}),
+                ...(options.mode !== undefined ? { mode: options.mode } : {}),
+                ...(options.signedTtlSeconds !== undefined
+                    ? { signedTtlSeconds: options.signedTtlSeconds }
+                    : {}),
+            });
+            response.header('cache-control', cacheControl);
+            if (result.vary)
+                response.header('vary', result.vary);
+            if (result.kind === 'redirect')
+                return response.redirect(result.url);
+            response.header('content-type', result.mimeType);
+            if (result.size !== undefined)
+                response.header('content-length', String(result.size));
+            if (result.fileName) {
+                response.header('content-disposition', inlineDisposition(result.fileName));
+            }
+            return response.stream(result.stream);
+        }
+        catch (error) {
+            const status = httpStatusOf(error);
+            if (status === undefined)
+                throw error;
+            const { code, message } = error;
+            const replied = response.status(status);
+            return replied.json?.({ code, message });
+        }
+    }
+    /**
+     * A ready AdonisJS route handler that serves a media record — the delivery route every app was
+     * hand-writing:
+     *
+     * ```ts
+     * const serveMedia = media.access.deliveryRoute({ authorize: authorizers.owner() })
+     * router.get('/media/:id', serveMedia)
+     * ```
+     *
+     * - authorizes the read (`authorize`, or the collection's `access.read`; neither ⇒ refused),
+     *   unless the URL carries a valid `delivery.signing` signature — that signature IS the
+     *   authorization the app made when it issued the URL;
+     * - passes `?conversion`, `?w`, `?q`, `Accept`, `?exp`, `?sig` through (on-demand resize,
+     *   format negotiation, signed URLs);
+     * - redirects or streams per `delivery.mode`, with `Content-Type`, `Content-Length`,
+     *   `Content-Disposition: inline`, `Cache-Control` (private by default) and `Vary: Accept`;
+     * - answers the library's errors as HTTP: 404 (unknown record or conversion), 400 (size not
+     *   allowed, not an image), 401/403 (not signed in / not allowed / bad signature).
+     */
+    deliveryRoute(options = {}) {
+        const param = options.param ?? 'id';
+        return (ctx) => this.serve(ctx, String(ctx.params[param] ?? ''), options);
+    }
+}
+/** The HTTP status for an error the delivery route answers itself; `undefined` ⇒ rethrow. */
+function httpStatusOf(error) {
+    if (error instanceof MediaAccessDeniedError)
+        return error.status;
+    if (error instanceof DeliverySignatureError)
+        return 403;
+    if (error instanceof MediaNotFoundError)
+        return 404;
+    if (error instanceof ConversionNotDefinedError)
+        return 404;
+    if (error instanceof TransformNotReadyError)
+        return 404;
+    if (error instanceof ImageSizeNotAllowedError)
+        return 400;
+    if (error instanceof NotAnImageError)
+        return 400;
+    return undefined;
+}
+function stringParam(value) {
+    const first = Array.isArray(value) ? value[0] : value;
+    if (first === undefined || first === null)
+        return undefined;
+    return String(first);
+}
+/** `inline; filename="…"; filename*=UTF-8''…` — ASCII fallback plus the exact name (RFC 6266). */
+function inlineDisposition(fileName) {
+    const ascii = fileName.replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_');
+    // RFC 5987 `attr-char` excludes ' ( ) * — which encodeURIComponent leaves alone; `'` would
+    // even end the value early.
+    const encoded = encodeURIComponent(fileName).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+    return `inline; filename="${ascii}"; filename*=UTF-8''${encoded}`;
+}
+//# sourceMappingURL=media_access.js.map

package/dist/src/media_access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media_access.js","sourceRoot":"","sources":["../../src/media_access.ts"],"names":[],"mappings":"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"}

package/dist/src/media_collection.d.ts

@@ -1,3 +1,4 @@
+import type { MediaCollectionAccess } from './access.js';
 import type { ConversionPreset } from './image_processor.js';
 import type { Transformer } from './transformer.js';
 /** Widths a `responsive: true` collection generates (those below the original's width). */
@@ -43,6 +44,16 @@ export interface MediaCollectionConfig {
      * also on `attachExisting`. Only images with something to strip are rewritten.
      */
     stripMetadata?: boolean;
+    /**
+     * Who may read files of this collection and who may put files into it — applied by
+     * `media.access` (its `deliveryRoute()`, `image()`, `authorize()`). `'public'` allows everyone;
+     * an absent rule denies. Build rules with `authorizers` (and the authkit/authz integrations):
+     *
+     * ```ts
+     * { name: 'avatar', access: { read: authorizers.owner(), write: authorizers.authenticated() } }
+     * ```
+     */
+    access?: MediaCollectionAccess;
 }
 export declare class MediaCollectionRegistry {
     private readonly map;