Skip to content

[client-preset] Make persisted docs default hashing algorithm sha256, and follow recommended format #10652

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eddeee888 merged 5 commits into from
Mar 24, 2026
Merged

[client-preset] Make persisted docs default hashing algorithm sha256, and follow recommended format #10652

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
15e05be
Update default hash to be sha256 for persisted documents
eddeee888 Mar 23, 2026
b4751ac
Add changeset
eddeee888 Mar 23, 2026
6f4b044
chore(dependencies): updated changesets for modified dependencies
github-actions[bot] Mar 23, 2026
33f45bf
Update tests
eddeee888 Mar 23, 2026
16da7db
chore(dependencies): updated changesets for modified dependencies
github-actions[bot] Mar 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/sad-rules-sell.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@graphql-codegen/client-preset': major
---

BREAKING CHANGES: The default hashing algorithm is now sha256 instead of sha1. Generated sha256 format also follows the standard outlined in https://github.com/graphql/graphql-over-http/blob/52d56fb36d51c17e08a920510a23bdc2f6a720be/spec/Appendix%20A%20--%20Persisted%20Documents.md#sha256-hex-document-identifier
2 changes: 1 addition & 1 deletion examples/persisted-documents-string-mode/src/gql/graphql.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,5 +33,5 @@ export const HelloQueryDocument = new TypedDocumentString(
hello
}
`,
{ hash: '86f01e23de1c770cabbc35b2d87f2e5fd7557b6f' }
{ hash: 'sha256:4c3f5d98b02279859b4c0c4efdba9553ac7acf89b9b0785eb24be68d5a67e6e8' }
) as unknown as TypedDocumentString<HelloQueryQuery, HelloQueryQueryVariables>;
2 changes: 1 addition & 1 deletion examples/persisted-documents-string-mode/src/gql/persisted-documents.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
"86f01e23de1c770cabbc35b2d87f2e5fd7557b6f": "query HelloQuery { hello }"
"sha256:4c3f5d98b02279859b4c0c4efdba9553ac7acf89b9b0785eb24be68d5a67e6e8": "query HelloQuery { hello }"
}
2 changes: 1 addition & 1 deletion examples/persisted-documents/src/gql/graphql.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ export type HelloQueryQueryVariables = Exact<{ [key: string]: never }>;
export type HelloQueryQuery = { hello: string };

export const HelloQueryDocument = {
__meta__: { hash: '86f01e23de1c770cabbc35b2d87f2e5fd7557b6f' },
__meta__: { hash: 'sha256:4c3f5d98b02279859b4c0c4efdba9553ac7acf89b9b0785eb24be68d5a67e6e8' },
kind: 'Document',
definitions: [
{
Expand Down
2 changes: 1 addition & 1 deletion examples/persisted-documents/src/gql/persisted-documents.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
"86f01e23de1c770cabbc35b2d87f2e5fd7557b6f": "query HelloQuery { hello }"
"sha256:4c3f5d98b02279859b4c0c4efdba9553ac7acf89b9b0785eb24be68d5a67e6e8": "query HelloQuery { hello }"
}
4 changes: 2 additions & 2 deletions packages/presets/client/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ export type ClientPresetConfig = {
* The algorithm parameter is typed with known algorithms and as a string rather than a union because it solely depends on Crypto's algorithms supported
* by the version of OpenSSL on the platform.
*
* @default `sha1`
* @default `sha256`
*/
hashAlgorithm?: 'sha1' | 'sha256' | (string & {}) | ((operation: string) => string);
};
Expand Down Expand Up @@ -164,7 +164,7 @@ export const preset: Types.OutputPreset<ClientPresetConfig> = {
hashAlgorithm:
(typeof options.presetConfig.persistedDocuments === 'object' &&
options.presetConfig.persistedDocuments.hashAlgorithm) ||
'sha1',
'sha256',
}
: null;

Expand Down
7 changes: 6 additions & 1 deletion packages/presets/client/src/persisted-documents.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ const CONNECTION_DIRECTIVE_NAME = 'connection';

/**
* This function generates a hash from a document node.
* When `sha256` algorithm is used, the hash should be prefixed with `sha256:`
* https://github.com/graphql/graphql-over-http/blob/52d56fb36d51c17e08a920510a23bdc2f6a720be/spec/Appendix%20A%20--%20Persisted%20Documents.md#sha256-hex-document-identifier
*/
export function generateDocumentHash(
operation: string,
Expand All @@ -17,7 +19,10 @@ export function generateDocumentHash(
}
const shasum = crypto.createHash(algorithm);
shasum.update(operation);
return shasum.digest('hex');

const algorithmPrefix = algorithm === 'sha256' ? 'sha256:' : '';
Copy link
Copy Markdown
Collaborator Author

@eddeee888 eddeee888 Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @benjie @n1ru4l , the doc only says that when sha256 is used, it should be prefixed with sha256:. Therefore, I haven't applied this logic to sha1 . Keen to hear thoughts whether we should ?

Copy link
Copy Markdown
Contributor

@benjie benjie Mar 23, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From the spec:

The {prefix}
identifies the method of identification used. Applications may use their own
identification methods by ensuring that the prefix starts x-; otherwise, all
prefixes are reserved for reasons of future expansion.

I would advise avoiding having a : in the doc ID at all for SHA1, but you can do x-sha1: or x-guild-sha1: or similar instead if you want. (Later you can propose we adopt sha1: as a supported prefix if you want.)

(What you have currently looks correct.)

Copy link
Copy Markdown
Collaborator Author

@eddeee888 eddeee888 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah thanks for the extract from spec. Makes sense!
I'll keep it as-is then, thanks for your advice 🙏


return algorithmPrefix + shasum.digest('hex');
}

/**
Expand Down
44 changes: 22 additions & 22 deletions packages/presets/client/tests/client-preset.spec.ts
View file
Open in desktop

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions website/src/pages/plugins/presets/preset-client.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -496,7 +496,7 @@ console.log(await response.json())

### Hashing algorithm

To override the default hash algorithm of sha1 set `persistedDocuments.hashAlgorithm`
To override the default hash algorithm of sha256 set `persistedDocuments.hashAlgorithm`

```ts filename="codegen.ts" {10-12}
import { type CodegenConfig } from '@graphql-codegen/cli'
Expand All @@ -509,7 +509,7 @@ const config: CodegenConfig = {
preset: 'client',
presetConfig: {
persistedDocuments: {
hashAlgorithm: 'sha256'
hashAlgorithm: 'sha1'
}
}
}
Expand Down