// =====================================================================
// DEPRECATED — DO NOT USE FOR ACCESS DECISIONS
// =====================================================================
//
// This file used to expose a generic ACL subsystem (`ObjectAccessGroupType`,
// `createObjectAccessGroup`, `canAccessObject`) carried over from a starter
// blueprint. The subsystem was never wired into any route — the empty enum
// and throwing factory were a security trap (MR-M7 in
// `.local/security/manual-review.md`): any future caller would have either
// silently 403'd every download, or "fixed" the failure by re-opening the
// route and re-introducing MR-H1 deliberately.
//
// Authorization for `GET /api/storage/objects/*` now lives in
// `lib/objectAuthz.ts` and uses an entity-lookup model (per-entity DB
// query → per-entity read role). DO NOT add new callers of this file
// for permission decisions.
//
// What remains here is the bare minimum needed to keep
// `objectStorage.downloadObject` working: it consults the cached ACL
// metadata only to decide between `Cache-Control: public` and
// `Cache-Control: private` headers. Because `setAclPolicy` is no
// longer called from anywhere in the app, `getAclPolicy` will always
// return null on production data, so every response is sent with
// `Cache-Control: private` — the safe default.
// =====================================================================

export enum ObjectPermission {
  READ = "read",
  WRITE = "write",
}

// Retained as a type so callers (objectStorage.ts) keep compiling. The
// `aclRules`/`group` machinery has been removed; only the
// owner/visibility hint is kept for the cache-header decision.
export interface ObjectAclPolicy {
  owner: string;
  visibility: "public" | "private";
}

/**
 * Driver-agnostic stored-object handle. Replaces the old `File` type
 * from `@google-cloud/storage` so route handlers (which operate on
 * the result opaquely) don't depend on a specific storage backend.
 */
export interface StoredObject {
  bucketName: string;
  objectName: string;
  exists(): Promise<boolean>;
  getMetadata(): Promise<{
    contentType?: string;
    size?: number;
    aclPolicy?: ObjectAclPolicy | null;
  }>;
  createReadStream(): NodeJS.ReadableStream;
  /**
   * Reads the entire object into a Buffer. The single-element tuple shape
   * mirrors `@google-cloud/storage`'s `File.download()` so legacy callers
   * (e.g. PDF logo loader) keep working without refactoring.
   */
  download(): Promise<[Buffer]>;
  setAclPolicy(policy: ObjectAclPolicy): Promise<void>;
  getAclPolicy(): Promise<ObjectAclPolicy | null>;
}

/**
 * @deprecated Use `canUserReadObjectPath` from `lib/objectAuthz.ts`
 * instead. This shim only exists so callers that historically imported
 * it keep type-checking; it always denies.
 */
export async function canAccessObject(_args: {
  userId?: string;
  objectFile: StoredObject;
  requestedPermission: ObjectPermission;
}): Promise<boolean> {
  return false;
}
