@grantjs/schema 1.8.0 → 1.9.1

package/src/operations/uploads/request-my-user-picture-upload-url.graphql

@@ -0,0 +1,11 @@
+mutation RequestMyUserPictureUploadUrl($input: RequestMyUserPictureUploadUrlInput!) {
+  requestMyUserPictureUploadUrl(input: $input) {
+    url
+    method
+    expiresAt
+    headers {
+      name
+      value
+    }
+  }
+}

package/src/operations/uploads/request-organization-picture-upload-url.graphql

@@ -0,0 +1,11 @@
+mutation RequestOrganizationPictureUploadUrl($input: RequestOrganizationPictureUploadUrlInput!) {
+  requestOrganizationPictureUploadUrl(input: $input) {
+    url
+    method
+    expiresAt
+    headers {
+      name
+      value
+    }
+  }
+}

package/src/operations/uploads/request-project-app-picture-upload-url.graphql

@@ -0,0 +1,11 @@
+mutation RequestProjectAppPictureUploadUrl($input: RequestProjectAppPictureUploadUrlInput!) {
+  requestProjectAppPictureUploadUrl(input: $input) {
+    url
+    method
+    expiresAt
+    headers {
+      name
+      value
+    }
+  }
+}

package/src/operations/uploads/request-project-picture-upload-url.graphql

@@ -0,0 +1,11 @@
+mutation RequestProjectPictureUploadUrl($input: RequestProjectPictureUploadUrlInput!) {
+  requestProjectPictureUploadUrl(input: $input) {
+    url
+    method
+    expiresAt
+    headers {
+      name
+      value
+    }
+  }
+}

package/src/operations/uploads/request-user-picture-upload-url.graphql

@@ -0,0 +1,11 @@
+mutation RequestUserPictureUploadUrl($input: RequestUserPictureUploadUrlInput!) {
+  requestUserPictureUploadUrl(input: $input) {
+    url
+    method
+    expiresAt
+    headers {
+      name
+      value
+    }
+  }
+}

package/src/project-oauth.types.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+
+import { isProjectOAuthThemeMode } from './project-oauth.types';
+
+describe('isProjectOAuthThemeMode', () => {
+  it('accepts the hosted OAuth appearance values', () => {
+    expect(isProjectOAuthThemeMode('light')).toBe(true);
+    expect(isProjectOAuthThemeMode('dark')).toBe(true);
+    expect(isProjectOAuthThemeMode('system')).toBe(true);
+  });
+
+  it('rejects unset or unknown values', () => {
+    expect(isProjectOAuthThemeMode(null)).toBe(false);
+    expect(isProjectOAuthThemeMode(undefined)).toBe(false);
+    expect(isProjectOAuthThemeMode('sepia')).toBe(false);
+    expect(isProjectOAuthThemeMode('DARK')).toBe(false);
+  });
+});

package/src/project-oauth.types.ts

@@ -3,6 +3,16 @@
  * Used by project app-info and consent REST endpoints; shared by API and web client.
  */
 
+/** Forced appearance on hosted OAuth pages. Null keeps the visitor's Grant theme. */
+export const PROJECT_OAUTH_THEME_MODES = ['light', 'dark', 'system'] as const;
+export type ProjectOAuthThemeMode = (typeof PROJECT_OAUTH_THEME_MODES)[number];
+
+export function isProjectOAuthThemeMode(value: unknown): value is ProjectOAuthThemeMode {
+  return (
+    typeof value === 'string' && (PROJECT_OAUTH_THEME_MODES as readonly string[]).includes(value)
+  );
+}
+
 /** Scope label returned by project app-info and consent-info endpoints. */
 export interface ProjectAppScopeInfo {
   slug: string;
@@ -13,6 +23,11 @@ export interface ProjectAppScopeInfo {
 /** Response from GET /api/auth/project/app-info (public app metadata and scopes). */
 export interface ProjectAppPublicInfo {
   name: string | null;
+  projectName: string | null;
+  pictureUrl: string | null;
+  primaryColor: string | null;
+  showHelpPanel: boolean;
+  themeMode: ProjectOAuthThemeMode | null;
   enabledProviders: string[] | null;
   scopes: ProjectAppScopeInfo[];
 }
@@ -22,11 +37,18 @@ export interface ProjectConsentInfoUser {
   displayName: string;
   email: string | null;
   pictureUrl: string | null;
+  /** Provider used for this sign-in (email, github, google). */
+  provider: string | null;
 }
 
 /** Response from GET /api/auth/project/consent-info (app name, granted scopes, user). */
 export interface ProjectConsentInfo {
   name: string | null;
+  projectName: string | null;
+  pictureUrl: string | null;
+  primaryColor: string | null;
+  showHelpPanel: boolean;
+  themeMode: ProjectOAuthThemeMode | null;
   scopes: ProjectAppScopeInfo[];
   user: ProjectConsentInfoUser | null;
 }

package/src/schema/me/inputs/confirm-my-project-membership-picture-upload.graphql

@@ -0,0 +1,4 @@
+input ConfirmMyProjectMembershipPictureUploadInput {
+  projectId: ID!
+  filename: String!
+}

package/src/schema/me/inputs/confirm-my-user-picture-upload.graphql

@@ -0,0 +1,8 @@
+"""
+`filename` is repeated from the request step rather than carried in a token: the
+storage path is re-derived server-side from the caller's identity both times, so
+nothing the client sends can point the confirmation at another user's object.
+"""
+input ConfirmMyUserPictureUploadInput {
+  filename: String!
+}

package/src/schema/me/inputs/request-my-project-membership-picture-upload-url.graphql

@@ -0,0 +1,11 @@
+input RequestMyProjectMembershipPictureUploadUrlInput {
+  projectId: ID!
+  filename: String!
+  contentType: String!
+
+  """
+  Exact byte length the client will send. Validated against the upload policy
+  before a URL is issued, and committed to by the URL itself.
+  """
+  contentLength: Int!
+}

package/src/schema/me/inputs/request-my-user-picture-upload-url.graphql

@@ -0,0 +1,11 @@
+input RequestMyUserPictureUploadUrlInput {
+  filename: String!
+  contentType: String!
+
+  """
+  Exact byte length the client will send. Validated against the upload policy
+  before a URL is issued, and committed to by the URL itself — a body of any
+  other length is refused by the store.
+  """
+  contentLength: Int!
+}

package/src/schema/me/mutations/confirm-my-project-membership-picture-upload.graphql

@@ -0,0 +1,10 @@
+extend type Mutation {
+  """
+  Record a direct upload of a project-membership picture that has completed.
+  Re-checks membership and reads the object back from storage before anything is
+  written to the membership.
+  """
+  confirmMyProjectMembershipPictureUpload(
+    input: ConfirmMyProjectMembershipPictureUploadInput!
+  ): UploadUserPictureResult!
+}

package/src/schema/me/mutations/confirm-my-user-picture-upload.graphql

@@ -0,0 +1,9 @@
+extend type Mutation {
+  """
+  Record a direct upload that has completed. Reads the object back from storage
+  to confirm it exists and is within the size policy — what the client claimed
+  when it asked for the URL is not evidence — then points the user's picture at
+  it.
+  """
+  confirmMyUserPictureUpload(input: ConfirmMyUserPictureUploadInput!): UploadUserPictureResult!
+}

package/src/schema/me/mutations/request-my-project-membership-picture-upload-url.graphql

@@ -0,0 +1,13 @@
+extend type Mutation {
+  """
+  Ask for a URL to upload the signed-in user's picture for one project
+  membership, directly to storage.
+
+  Membership is checked before a URL exists, not only when the upload is
+  recorded: a URL is a write capability, so issuing one for a project you do not
+  belong to is the thing to prevent, not to detect afterwards.
+  """
+  requestMyProjectMembershipPictureUploadUrl(
+    input: RequestMyProjectMembershipPictureUploadUrlInput!
+  ): UploadUrl!
+}

package/src/schema/me/mutations/request-my-user-picture-upload-url.graphql

@@ -0,0 +1,12 @@
+extend type Mutation {
+  """
+  Ask for a URL to upload the signed-in user's picture directly to storage,
+  without the bytes passing through this API.
+
+  Validates content type, extension and size **before** issuing the URL, and
+  binds the URL to a path derived from the caller's own identity. Call
+  `confirmMyUserPictureUpload` once the PUT succeeds; until then nothing is
+  recorded against the user.
+  """
+  requestMyUserPictureUploadUrl(input: RequestMyUserPictureUploadUrlInput!): UploadUrl!
+}

package/src/schema/organizations/inputs/confirm-organization-picture-upload.graphql

@@ -0,0 +1,9 @@
+"""
+`filename` is repeated from the request step rather than carried in a token: the
+storage path is re-derived server-side from the organization id both times.
+"""
+input ConfirmOrganizationPictureUploadInput {
+  scope: Scope!
+  organizationId: ID!
+  filename: String!
+}

package/src/schema/organizations/inputs/request-organization-picture-upload-url.graphql

@@ -0,0 +1,12 @@
+input RequestOrganizationPictureUploadUrlInput {
+  scope: Scope!
+  organizationId: ID!
+  filename: String!
+  contentType: String!
+
+  """
+  Exact byte length the client will send. Validated against the upload policy
+  before a URL is issued, and committed to by the URL itself.
+  """
+  contentLength: Int!
+}

package/src/schema/organizations/mutations/confirm-organization-picture-upload.graphql

@@ -0,0 +1,10 @@
+extend type Mutation {
+  """
+  Record a direct organization-logo upload that has completed. Reads the object
+  back from storage to confirm it exists and is within the size policy, then
+  stores the object key on the organization (`picture_path`).
+  """
+  confirmOrganizationPictureUpload(
+    input: ConfirmOrganizationPictureUploadInput!
+  ): UploadOrganizationPictureResult!
+}

package/src/schema/organizations/mutations/request-organization-picture-upload-url.graphql

@@ -0,0 +1,12 @@
+extend type Mutation {
+  """
+  Ask for a URL to upload an organization logo directly to storage, without the
+  bytes passing through this API.
+
+  Validates content type, extension and size **before** issuing the URL, and
+  binds the URL to a path derived from the organization id. Call
+  `confirmOrganizationPictureUpload` once the PUT succeeds; until then nothing
+  is recorded against the organization.
+  """
+  requestOrganizationPictureUploadUrl(input: RequestOrganizationPictureUploadUrlInput!): UploadUrl!
+}

package/src/schema/project-apps/inputs/clear-project-app-picture.graphql

@@ -0,0 +1,4 @@
+input ClearProjectAppPictureInput {
+  scope: Scope!
+  projectAppId: ID!
+}

package/src/schema/project-apps/inputs/confirm-project-app-picture-upload.graphql

@@ -0,0 +1,9 @@
+"""
+`filename` is repeated from the request step rather than carried in a token: the
+storage path is re-derived server-side from the project-app id both times.
+"""
+input ConfirmProjectAppPictureUploadInput {
+  scope: Scope!
+  projectAppId: ID!
+  filename: String!
+}

package/src/schema/project-apps/inputs/request-project-app-picture-upload-url.graphql

@@ -0,0 +1,12 @@
+input RequestProjectAppPictureUploadUrlInput {
+  scope: Scope!
+  projectAppId: ID!
+  filename: String!
+  contentType: String!
+
+  """
+  Exact byte length the client will send. Validated against the upload policy
+  before a URL is issued, and committed to by the URL itself.
+  """
+  contentLength: Int!
+}

package/src/schema/project-apps/inputs/update-project-app.graphql

@@ -5,6 +5,18 @@ input UpdateProjectAppInput {
   """
   name: String
   """
+  Brand hex (`#RRGGBB`). Null inherits the project color.
+  """
+  primaryColor: String
+  """
+  Whether the OAuth help panel is shown. Null inherits the project setting.
+  """
+  showHelpPanel: Boolean
+  """
+  Forced OAuth appearance (`light`, `dark`, `system`). Null keeps the visitor's Grant theme.
+  """
+  themeMode: String
+  """
   Allowed redirect URIs for OAuth callback. If provided, at least one required.
   """
   redirectUris: [String!]

package/src/schema/project-apps/inputs/upload-project-app-picture.graphql

@@ -0,0 +1,7 @@
+input UploadProjectAppPictureInput {
+  scope: Scope!
+  projectAppId: ID!
+  file: String!
+  filename: String!
+  contentType: String!
+}

package/src/schema/project-apps/mutations/clear-project-app-picture.graphql

@@ -0,0 +1,6 @@
+extend type Mutation {
+  """
+  Clear the project-app logo. Does not delete the stored object.
+  """
+  clearProjectAppPicture(input: ClearProjectAppPictureInput!): ProjectApp!
+}

package/src/schema/project-apps/mutations/confirm-project-app-picture-upload.graphql

@@ -0,0 +1,10 @@
+extend type Mutation {
+  """
+  Record a direct project-app-logo upload that has completed. Reads the object
+  back from storage to confirm it exists and is within the size policy, then
+  stores the object key on the app (`picture_path`).
+  """
+  confirmProjectAppPictureUpload(
+    input: ConfirmProjectAppPictureUploadInput!
+  ): UploadProjectAppPictureResult!
+}

package/src/schema/project-apps/mutations/request-project-app-picture-upload-url.graphql

@@ -0,0 +1,12 @@
+extend type Mutation {
+  """
+  Ask for a URL to upload a project-app logo directly to storage, without the
+  bytes passing through this API.
+
+  Validates content type, extension and size **before** issuing the URL, and
+  binds the URL to a path derived from the project-app id. Call
+  `confirmProjectAppPictureUpload` once the PUT succeeds; until then nothing
+  is recorded against the app.
+  """
+  requestProjectAppPictureUploadUrl(input: RequestProjectAppPictureUploadUrlInput!): UploadUrl!
+}

package/src/schema/project-apps/mutations/upload-project-app-picture.graphql

@@ -0,0 +1,6 @@
+extend type Mutation {
+  """
+  Upload a project-app logo and persist its public URL.
+  """
+  uploadProjectAppPicture(input: UploadProjectAppPictureInput!): UploadProjectAppPictureResult!
+}

package/src/schema/project-apps/types/project-app.graphql

@@ -3,6 +3,19 @@ type ProjectApp implements Auditable {
   projectId: ID!
   clientId: String!
   name: String
+  pictureUrl: String
+  """
+  Brand hex (`#RRGGBB`). Null inherits the project color.
+  """
+  primaryColor: String
+  """
+  Whether the OAuth help panel is shown. Null inherits the project setting.
+  """
+  showHelpPanel: Boolean
+  """
+  Forced OAuth appearance (`light`, `dark`, `system`). Null keeps the visitor's Grant theme.
+  """
+  themeMode: String
   redirectUris: [String!]!
   scopes: [String!]
   """

package/src/schema/project-apps/types/upload-project-app-picture-result.graphql

@@ -0,0 +1,4 @@
+type UploadProjectAppPictureResult {
+  url: String!
+  path: String!
+}

package/src/schema/projects/inputs/clear-project-picture.graphql

@@ -0,0 +1,4 @@
+input ClearProjectPictureInput {
+  scope: Scope!
+  projectId: ID!
+}

package/src/schema/projects/inputs/confirm-project-picture-upload.graphql

@@ -0,0 +1,9 @@
+"""
+`filename` is repeated from the request step rather than carried in a token: the
+storage path is re-derived server-side from the project id both times.
+"""
+input ConfirmProjectPictureUploadInput {
+  scope: Scope!
+  projectId: ID!
+  filename: String!
+}

package/src/schema/projects/inputs/request-project-picture-upload-url.graphql

@@ -0,0 +1,12 @@
+input RequestProjectPictureUploadUrlInput {
+  scope: Scope!
+  projectId: ID!
+  filename: String!
+  contentType: String!
+
+  """
+  Exact byte length the client will send. Validated against the upload policy
+  before a URL is issued, and committed to by the URL itself.
+  """
+  contentLength: Int!
+}

package/src/schema/projects/inputs/update-project.graphql

@@ -2,6 +2,14 @@ input UpdateProjectInput {
   scope: Scope!
   name: String
   description: String
+  """
+  Brand hex (`#RRGGBB`). Null resets to Grant's default.
+  """
+  primaryColor: String
+  """
+  Whether the OAuth help panel is shown. Null resets to Grant's default (shown).
+  """
+  showHelpPanel: Boolean
   tagIds: [ID!]
   primaryTagId: ID
 }

package/src/schema/projects/inputs/upload-project-picture.graphql

@@ -0,0 +1,7 @@
+input UploadProjectPictureInput {
+  scope: Scope!
+  projectId: ID!
+  file: String!
+  filename: String!
+  contentType: String!
+}

package/src/schema/projects/mutations/clear-project-picture.graphql

@@ -0,0 +1,6 @@
+extend type Mutation {
+  """
+  Clear the project logo. Does not delete the stored object.
+  """
+  clearProjectPicture(input: ClearProjectPictureInput!): Project!
+}

package/src/schema/projects/mutations/confirm-project-picture-upload.graphql

@@ -0,0 +1,8 @@
+extend type Mutation {
+  """
+  Record a direct project-logo upload that has completed. Reads the object
+  back from storage to confirm it exists and is within the size policy, then
+  stores the object key on the project (`picture_path`).
+  """
+  confirmProjectPictureUpload(input: ConfirmProjectPictureUploadInput!): UploadProjectPictureResult!
+}

package/src/schema/projects/mutations/request-project-picture-upload-url.graphql

@@ -0,0 +1,12 @@
+extend type Mutation {
+  """
+  Ask for a URL to upload a project logo directly to storage, without the
+  bytes passing through this API.
+
+  Validates content type, extension and size **before** issuing the URL, and
+  binds the URL to a path derived from the project id. Call
+  `confirmProjectPictureUpload` once the PUT succeeds; until then nothing
+  is recorded against the project.
+  """
+  requestProjectPictureUploadUrl(input: RequestProjectPictureUploadUrlInput!): UploadUrl!
+}

package/src/schema/projects/mutations/upload-project-picture.graphql

@@ -0,0 +1,6 @@
+extend type Mutation {
+  """
+  Upload a project logo and persist its public URL.
+  """
+  uploadProjectPicture(input: UploadProjectPictureInput!): UploadProjectPictureResult!
+}

package/src/schema/projects/types/project.graphql

@@ -3,6 +3,15 @@ type Project implements Auditable {
   name: String!
   slug: String!
   description: String
+  pictureUrl: String
+  """
+  Brand hex (`#RRGGBB`). Null uses Grant's default OAuth theme.
+  """
+  primaryColor: String
+  """
+  Whether the OAuth help panel is shown. Null uses Grant's default (shown).
+  """
+  showHelpPanel: Boolean
   roles: [Role!]
   groups: [Group!]
   permissions: [Permission!]

package/src/schema/projects/types/upload-project-picture-result.graphql

@@ -0,0 +1,4 @@
+type UploadProjectPictureResult {
+  url: String!
+  path: String!
+}

package/src/schema/uploads/types/upload-url.graphql

@@ -0,0 +1,33 @@
+"""
+A bounded, time-limited URL the client writes bytes to directly.
+
+The URL is a bearer capability: it permits exactly `contentLength` bytes of
+exactly `contentType` at exactly one server-derived path, until `expiresAt`.
+It is not single-use and cannot be revoked, so it is short-lived by design.
+"""
+type UploadUrl {
+  """
+  Absolute for object stores; application-relative for targets this API serves
+  itself. Resolve it against the API origin before using it.
+  """
+  url: String!
+
+  "HTTP method the client must use. Always PUT today."
+  method: String!
+
+  """
+  Headers the client must set verbatim. `Content-Length` is deliberately absent:
+  browsers set it from the body and forbid setting it by hand, even though the
+  URL commits to the value.
+  """
+  headers: [UploadUrlHeader!]!
+
+  "Instant after which the store refuses the URL."
+  expiresAt: Date!
+}
+
+"A header the client must send with the direct upload."
+type UploadUrlHeader {
+  name: String!
+  value: String!
+}

package/src/schema/users/inputs/confirm-user-picture-upload.graphql

@@ -0,0 +1,5 @@
+input ConfirmUserPictureUploadInput {
+  scope: Scope!
+  userId: ID!
+  filename: String!
+}

package/src/schema/users/inputs/request-user-picture-upload-url.graphql

@@ -0,0 +1,12 @@
+input RequestUserPictureUploadUrlInput {
+  scope: Scope!
+  userId: ID!
+  filename: String!
+  contentType: String!
+
+  """
+  Exact byte length the client will send. Validated against the upload policy
+  before a URL is issued, and committed to by the URL itself.
+  """
+  contentLength: Int!
+}

package/src/schema/users/mutations/confirm-user-picture-upload.graphql

@@ -0,0 +1,8 @@
+extend type Mutation {
+  """
+  Record a completed direct upload of another user's picture. Re-runs the scope
+  and permission checks, then reads the object back from storage before writing
+  the picture to the user or to their project membership, as scope dictates.
+  """
+  confirmUserPictureUpload(input: ConfirmUserPictureUploadInput!): UploadUserPictureResult!
+}

package/src/schema/users/mutations/request-user-picture-upload-url.graphql

@@ -0,0 +1,12 @@
+extend type Mutation {
+  """
+  Ask for a URL to upload another user's picture directly to storage.
+
+  Unlike the `me` variants, the storage path here is derived from the **target**
+  user rather than the caller, so the permission check is the only thing standing
+  between a caller and another user's picture. It therefore runs before a URL is
+  issued — the same scope and self-managed-identity rules `uploadUserPicture`
+  applies — and again when the upload is confirmed.
+  """
+  requestUserPictureUploadUrl(input: RequestUserPictureUploadUrlInput!): UploadUrl!
+}

package/src/sdl-contract.test.ts

@@ -40,9 +40,18 @@ describe('operation documents', () => {
 
   // Pinned, not a floor: pass 5 slice 5 removed one file and two query operations
   // that were superseded by list queries, and a floor would have absorbed that
-  // silently. 116 before that slice, 115 after, 116 with upload-organization-picture.
+  // silently. 116 before that slice, 115 after it, 117 once part D's first
+  // direct-upload pair (`requestMyUserPictureUploadUrl`,
+  // `confirmMyUserPictureUpload`) arrived, and 121 with the two remaining targets —
+  // project membership and the administrator route — each another request/confirm
+  // pair. 122 after `main` merged in, which added `upload-organization-picture`.
+  // 124 after slice 17b: organization request/confirm (the last upload target).
+  // 132 after project branding: request/confirm/upload/clear for project and
+  // project-app pictures (eight operation documents).
+  // Updating this number is the point of the pin, not a nuisance: every change
+  // to it should be a line in a commit message.
   it('finds every document under src/operations', () => {
-    expect(files).toHaveLength(116);
+    expect(files).toHaveLength(132);
   });
 
   it.each(files.map((f) => [relative(process.cwd(), f), f]))('%s validates', (_label, file) => {