Infolab.HashIds.TagHelpers 1.0.0-preview.5

Infolab.HashIds

Turns integer identity values into short, non-sequential strings — 4242 becomes DbWgx6 — so database ids don't leak out through URLs and JSON payloads. Backed by Sqids.

This is obfuscation, not encryption. It stops casual enumeration of /people/1, /people/2, /people/3; it is not an access control mechanism.

Packages

Each builds on the one above it, so referencing Infolab.HashIds.Api brings Mvc and Core with it.

Getting started

dotnet add package Infolab.HashIds.Core

builder.Services.AddHashIds(builder.Configuration.GetSection(HashIdOptions.SectionName));

{
  "HashIds": {
    "Salt": "per-environment-secret",
    "MinLength": 6
  }
}

The salt is a secret — keep it in user secrets, environment variables or a key vault, not in source. Changing it changes every hash it produces, so ids already issued stop decoding.

Then annotate ids on your DTOs:

public class PersonDto
{
    [HashIdProperty] public int Id { get; set; }
    [HashIdProperty] public long? ParentId { get; set; }
}

{ "id": "DbWgx6", "parentId": "F9ktkaA" }

int, int?, long and long? are all supported, and a given value encodes identically at either width — widening an id from int to long does not invalidate hashes already issued for it.

ASP.NET Core

Action parameters — mark the ones that are ids:

public async Task<IActionResult> Details([HashIdParam] int id) { ... }

Razor links — the referenced property must carry [HashIdProperty], which is checked at render time:

<a asp-controller="People" asp-action="Details" asp-hashid-id="PersonId">View</a>

<div hx-get hx-controller="People" hx-action="Details"
     hx-hashid-id="PersonId" hx-target="#panel">Load</div>

The prefix is asp-hashid- / hx-hashid-, not asp-route-hashid-. Anything nested under the built-in asp-route- / hx-route- prefixes gets bound by the built-in tag helper as well, which is a Razor compile error.

API results — when the result type lives in a layer that can't reference this library, register a projection instead of annotating it:

builder.Services.AddHashIdsApi(o =>
{
    o.MapResult<CreateCommandResult>((r, h) =>
        new HashIdEntityCreatedResult(h.Encode(r.Value), r.Succeeded, r.Errors));
});

builder.Services.AddOpenApi(o => o.AddSchemaTransformer<HashIdSchemaTransformer>());

Configuration

The default alphabet omits i, I, l, o, O and 0 so hashes survive being read aloud or transcribed.

Options are validated at startup (ValidateOnStart), so a bad alphabet fails the build-up rather than the first request.

Notes

• Ids must be non-negative; Encode throws on a negative value.
• Decode returns null for anything that isn't a single valid value, including one that would overflow int — use DecodeLong for ids that may exceed int.MaxValue.
• Replacing the implementation is just a matter of registering your own IHashIdService; decoration works too.

License

MIT — see LICENSE.