Dogcows Code - chaz/p5-File-KDBX/blob - lib/File/KDBX/Object.pm

   1 package File::KDBX::Object;
   2 # ABSTRACT: A KDBX database object
   3
   4 use warnings;
   5 use strict;
   6
   7 use Devel::GlobalDestruction;
   8 use File::KDBX::Constants qw(:bool);
   9 use File::KDBX::Error;
  10 use File::KDBX::Util qw(:uuid);
  11 use Hash::Util::FieldHash qw(fieldhashes);
  12 use List::Util qw(any first);
  13 use Ref::Util qw(is_arrayref is_plain_arrayref is_plain_hashref is_ref);
  14 use Scalar::Util qw(blessed weaken);
  15 use namespace::clean;
  16
  17 our $VERSION = '999.999'; # VERSION
  18
  19 fieldhashes \my (%KDBX, %PARENT, %TXNS, %REFS, %SIGNALS);
  20
  21 =method new
  22
  23     $object = File::KDBX::Object->new;
  24     $object = File::KDBX::Object->new(%attributes);
  25     $object = File::KDBX::Object->new(\%data);
  26     $object = File::KDBX::Object->new(\%data, $kdbx);
  27
  28 Construct a new KDBX object.
  29
  30 There is a subtlety to take note of. There is a significant difference between:
  31
  32     File::KDBX::Entry->new(username => 'iambatman');
  33
  34 and:
  35
  36     File::KDBX::Entry->new({username => 'iambatman'}); # WRONG
  37
  38 In the first, an empty object is first created and then initialized with whatever I<attributes> are given. In
  39 the second, a hashref is blessed and essentially becomes the object. The significance is that the hashref
  40 key-value pairs will remain as-is so the structure is expected to adhere to the shape of a raw B<Object>
  41 (which varies based on the type of object), whereas with the first the attributes will set the structure in
  42 the correct way (just like using the object accessors / getters / setters).
  43
  44 The second example isn't I<generally> wrong -- this type of construction is supported for a reason, to allow
  45 for working with KDBX objects at a low level -- but it is wrong in this specific case only because
  46 C<< {username => $str} >> isn't a valid raw KDBX entry object. The L</username> attribute is really a proxy
  47 for the C<UserName> string, so the equivalent raw entry object should be
  48 C<< {strings => {UserName => {value => $str}}} >>. These are roughly equivalent:
  49
  50     File::KDBX::Entry->new(username => 'iambatman');
  51     File::KDBX::Entry->new({strings => {UserName => {value => 'iambatman'}}});
  52
  53 If this explanation went over your head, that's fine. Just stick with the attributes since they are typically
  54 easier to use correctly and provide the most convenience. If in the future you think of some kind of KDBX
  55 object manipulation you want to do that isn't supported by the accessors and methods, just know you I<can>
  56 access an object's data directly.
  57
  58 =cut
  59
  60 sub new {
  61     my $class = shift;
  62
  63     # copy constructor
  64     return $_[0]->clone if @_ == 1 && blessed $_[0] && $_[0]->isa($class);
  65
  66     my $data;
  67     $data = shift if is_plain_hashref($_[0]);
  68
  69     my $kdbx;
  70     $kdbx = shift if @_ % 2 == 1;
  71
  72     my %args = @_;
  73     $args{kdbx} //= $kdbx if defined $kdbx;
  74
  75     my $self = bless $data // {}, $class;
  76     $self->init(%args);
  77     $self->_set_nonlazy_attributes if !$data;
  78     return $self;
  79 }
  80
  81 sub _set_nonlazy_attributes { die 'Not implemented' }
  82
  83 =method init
  84
  85     $object = $object->init(%attributes);
  86
  87 Called by the constructor to set attributes. You normally should not call this.
  88
  89 =cut
  90
  91 sub init {
  92     my $self = shift;
  93     my %args = @_;
  94
  95     while (my ($key, $val) = each %args) {
  96         if (my $method = $self->can($key)) {
  97             $self->$method($val);
  98         }
  99     }
 100
 101     return $self;
 102 }
 103
 104 =method wrap
 105
 106     $object = File::KDBX::Object->wrap($object);
 107
 108 Ensure that a KDBX object is blessed.
 109
 110 =cut
 111
 112 sub wrap {
 113     my $class   = shift;
 114     my $object  = shift;
 115     return $object if blessed $object && $object->isa($class);
 116     return $class->new(@_, @$object) if is_arrayref($object);
 117     return $class->new($object, @_);
 118 }
 119
 120 =method label
 121
 122     $label = $object->label;
 123     $object->label($label);
 124
 125 Get or set the object's label, a text string that can act as a non-unique identifier. For an entry, the label
 126 is its title string. For a group, the label is its name.
 127
 128 =cut
 129
 130 sub label { die 'Not implemented' }
 131
 132 =method clone
 133
 134     $object_copy = $object->clone(%options);
 135     $object_copy = File::KDBX::Object->new($object);
 136
 137 Make a clone of an object. By default the clone is indeed an exact copy that is connected to the same database
 138 but not actually included in the object tree (i.e. it has no parent group). Some options are allowed to get
 139 different effects:
 140
 141 =for :list
 142 * C<new_uuid> - If set, generate a new UUID for the copy (default: false)
 143 * C<parent> - If set, add the copy to the same parent group, if any (default: false)
 144 * C<relabel> - If set, append " - Copy" to the object's title or name (default: false)
 145 * C<entries> - If set, copy child entries, if any (default: true)
 146 * C<groups> - If set, copy child groups, if any (default: true)
 147 * C<history> - If set, copy entry history, if any (default: true)
 148 * C<reference_password> - Toggle whether or not cloned entry's Password string should be set as a field
 149     reference to the original entry's Password string (default: false)
 150 * C<reference_username> - Toggle whether or not cloned entry's UserName string should be set as a field
 151     reference to the original entry's UserName string (default: false)
 152
 153 =cut
 154
 155 my %CLONE = (entries => 1, groups => 1, history => 1);
 156 sub clone {
 157     my $self = shift;
 158     my %args = @_;
 159
 160     local $CLONE{new_uuid}              = $args{new_uuid} // $args{parent} // 0;
 161     local $CLONE{entries}               = $args{entries}  // 1;
 162     local $CLONE{groups}                = $args{groups}   // 1;
 163     local $CLONE{history}               = $args{history}  // 1;
 164     local $CLONE{reference_password}    = $args{reference_password} // 0;
 165     local $CLONE{reference_username}    = $args{reference_username} // 0;
 166
 167     require Storable;
 168     my $copy = Storable::dclone($self);
 169
 170     if ($args{relabel} and my $label = $self->label) {
 171         $copy->label("$label - Copy");
 172     }
 173     if ($args{parent} and my $parent = $self->group) {
 174         $parent->add_object($copy);
 175     }
 176
 177     return $copy;
 178 }
 179
 180 sub STORABLE_freeze {
 181     my $self    = shift;
 182     my $cloning = shift;
 183
 184     my $copy = {%$self};
 185     delete $copy->{entries} if !$CLONE{entries};
 186     delete $copy->{groups}  if !$CLONE{groups};
 187     delete $copy->{history} if !$CLONE{history};
 188
 189     return ($cloning ? Hash::Util::FieldHash::id($self) : ''), $copy;
 190 }
 191
 192 sub STORABLE_thaw {
 193     my $self    = shift;
 194     my $cloning = shift;
 195     my $addr    = shift;
 196     my $copy    = shift;
 197
 198     @$self{keys %$copy} = values %$copy;
 199
 200     if ($cloning) {
 201         my $kdbx = $KDBX{$addr};
 202         $self->kdbx($kdbx) if $kdbx;
 203     }
 204
 205     if (defined $self->{uuid}) {
 206         if (($CLONE{reference_password} || $CLONE{reference_username}) && $self->can('strings')) {
 207             my $uuid = format_uuid($self->{uuid});
 208             my $clone_obj = do {
 209                 local $CLONE{new_uuid}              = 0;
 210                 local $CLONE{entries}               = 1;
 211                 local $CLONE{groups}                = 1;
 212                 local $CLONE{history}               = 1;
 213                 local $CLONE{reference_password}    = 0;
 214                 local $CLONE{reference_username}    = 0;
 215                 # Clone only the entry's data and manually bless to avoid infinite recursion.
 216                 bless Storable::dclone({%$copy}), 'File::KDBX::Entry';
 217             };
 218             my $txn = $self->begin_work(snapshot => $clone_obj);
 219             if ($CLONE{reference_password}) {
 220                 $self->password("{REF:P\@I:$uuid}");
 221             }
 222             if ($CLONE{reference_username}) {
 223                 $self->username("{REF:U\@I:$uuid}");
 224             }
 225             $txn->commit;
 226         }
 227         $self->uuid(generate_uuid) if $CLONE{new_uuid};
 228     }
 229
 230     # Dualvars aren't cloned as dualvars, so dualify the icon.
 231     $self->icon_id($self->{icon_id}) if defined $self->{icon_id};
 232 }
 233
 234 =attr kdbx
 235
 236     $kdbx = $object->kdbx;
 237     $object->kdbx($kdbx);
 238
 239 Get or set the L<File::KDBX> instance connected with this object.
 240
 241 =cut
 242
 243 sub kdbx {
 244     my $self = shift;
 245     $self = $self->new if !ref $self;
 246     if (@_) {
 247         if (my $kdbx = shift) {
 248             $KDBX{$self} = $kdbx;
 249             weaken $KDBX{$self};
 250         }
 251         else {
 252             delete $KDBX{$self};
 253         }
 254     }
 255     $KDBX{$self} or throw 'Object is disconnected', object => $self;
 256 }
 257
 258 =method is_connected
 259
 260     $bool = $object->is_connected;
 261
 262 Determine whether or not an object is connected to a database.
 263
 264 =cut
 265
 266 sub is_connected {
 267     my $self = shift;
 268     return !!eval { $self->kdbx };
 269 }
 270
 271 =method id
 272
 273     $string_uuid = $object->id;
 274     $string_uuid = $object->id($delimiter);
 275
 276 Get the unique identifier for this object as a B<formatted> UUID string, typically for display purposes. You
 277 could use this to compare with other identifiers formatted with the same delimiter, but it is more efficient
 278 to use the raw UUID for that purpose (see L</uuid>).
 279
 280 A delimiter can optionally be provided to break up the UUID string visually. See
 281 L<File::KDBX::Util/format_uuid>.
 282
 283 =cut
 284
 285 sub id { format_uuid(shift->uuid, @_) }
 286
 287 =method group
 288
 289     $parent_group = $object->group;
 290     $object->group($parent_group);
 291
 292 Get or set the parent group to which an object belongs or C<undef> if it belongs to no group.
 293
 294 =cut
 295
 296 sub group {
 297     my $self = shift;
 298
 299     if (my $new_group = shift) {
 300         my $old_group = $self->group;
 301         return $new_group if Hash::Util::FieldHash::id($old_group) == Hash::Util::FieldHash::id($new_group);
 302         # move to a new parent
 303         $self->remove(signal => 0) if $old_group;
 304         $self->location_changed('now');
 305         $new_group->add_object($self);
 306     }
 307
 308     my $id   = Hash::Util::FieldHash::id($self);
 309     if (my $group = $PARENT{$self}) {
 310         my $method = $self->_parent_container;
 311         return $group if first { $id == Hash::Util::FieldHash::id($_) } @{$group->$method};
 312         delete $PARENT{$self};
 313     }
 314     # always get lineage from root to leaf because the other way requires parent, so it would be recursive
 315     my $lineage = $self->kdbx->_trace_lineage($self) or return;
 316     my $group = pop @$lineage or return;
 317     $PARENT{$self} = $group; weaken $PARENT{$self};
 318     return $group;
 319 }
 320
 321 sub _set_group {
 322     my $self = shift;
 323     if (my $parent = shift) {
 324         $PARENT{$self} = $parent;
 325         weaken $PARENT{$self};
 326     }
 327     else {
 328         delete $PARENT{$self};
 329     }
 330     return $self;
 331 }
 332
 333 ### Name of the parent attribute expected to contain the object
 334 sub _parent_container { die 'Not implemented' }
 335
 336 =method lineage
 337
 338     \@lineage = $object->lineage;
 339     \@lineage = $object->lineage($base_group);
 340
 341 Get the direct line of ancestors from C<$base_group> (default: the root group) to an object. The lineage
 342 includes the base group but I<not> the target object. Returns C<undef> if the target is not in the database
 343 structure. Returns an empty arrayref is the object itself is a root group.
 344
 345 =cut
 346
 347 sub lineage {
 348     my $self = shift;
 349     my $base = shift;
 350
 351     my $base_addr = $base ? Hash::Util::FieldHash::id($base) : 0;
 352
 353     # try leaf to root
 354     my @path;
 355     my $object = $self;
 356     while ($object = $object->group) {
 357         unshift @path, $object;
 358         last if $base_addr == Hash::Util::FieldHash::id($object);
 359     }
 360     return \@path if @path && ($base_addr == Hash::Util::FieldHash::id($path[0]) || $path[0]->is_root);
 361
 362     # try root to leaf
 363     return $self->kdbx->_trace_lineage($self, $base);
 364 }
 365
 366 =method remove
 367
 368     $object = $object->remove(%options);
 369
 370 Remove an object from its parent. If the object is a group, all contained objects stay with the object and so
 371 are removed as well. Options:
 372
 373 =for :list
 374 * C<signal> Whether or not to signal the removal to the connected database (default: true)
 375
 376 =cut
 377
 378 sub remove {
 379     my $self = shift;
 380     my $parent = $self->group;
 381     $parent->remove_object($self, @_) if $parent;
 382     $self->_set_group(undef);
 383     return $self;
 384 }
 385
 386 =method recycle
 387
 388     $object = $object->recycle;
 389
 390 Remove an object from its parent and add it to the connected database's recycle bin group.
 391
 392 =cut
 393
 394 sub recycle {
 395     my $self = shift;
 396     return $self->group($self->kdbx->recycle_bin);
 397 }
 398
 399 =method recycle_or_remove
 400
 401     $object = $object->recycle_or_remove;
 402
 403 Recycle or remove an object, depending on the connected database's L<File::KDBX/recycle_bin_enabled>. If the
 404 object is not connected to a database or is already in the recycle bin, remove it.
 405
 406 =cut
 407
 408 sub recycle_or_remove {
 409     my $self = shift;
 410     my $kdbx = eval { $self->kdbx };
 411     if ($kdbx && $kdbx->recycle_bin_enabled && !$self->is_recycled) {
 412         $self->recycle;
 413     }
 414     else {
 415         $self->remove;
 416     }
 417 }
 418
 419 =method is_recycled
 420
 421     $bool = $object->is_recycled;
 422
 423 Get whether or not an object is in a recycle bin.
 424
 425 =cut
 426
 427 sub is_recycled {
 428     my $self = shift;
 429     eval { $self->kdbx } or return FALSE;
 430     return !!($self->group && any { $_->is_recycle_bin } @{$self->lineage});
 431 }
 432
 433 ##############################################################################
 434
 435 =method tag_list
 436
 437     @tags = $entry->tag_list;
 438
 439 Get a list of tags, split from L</tag> using delimiters C<,>, C<.>, C<:>, C<;> and whitespace.
 440
 441 =cut
 442
 443 sub tag_list {
 444     my $self = shift;
 445     return grep { $_ ne '' } split(/[,\.:;]|\s+/, trim($self->tags) // '');
 446 }
 447
 448 =method custom_icon
 449
 450     $image_data = $object->custom_icon;
 451     $image_data = $object->custom_icon($image_data, %attributes);
 452
 453 Get or set an icon image. Returns C<undef> if there is no custom icon set. Setting a custom icon will change
 454 the L</custom_icon_uuid> attribute.
 455
 456 Custom icon attributes (supported in KDBX4.1 and greater):
 457
 458 =for :list
 459 * C<name> - Name of the icon (text)
 460 * C<last_modification_time> - Just what it says (datetime)
 461
 462 =cut
 463
 464 sub custom_icon {
 465     my $self = shift;
 466     my $kdbx = $self->kdbx;
 467     if (@_) {
 468         my $img = shift;
 469         my $uuid = defined $img ? $kdbx->add_custom_icon($img, @_) : undef;
 470         $self->icon_id(0) if $uuid;
 471         $self->custom_icon_uuid($uuid);
 472         return $img;
 473     }
 474     return $kdbx->custom_icon_data($self->custom_icon_uuid);
 475 }
 476
 477 =method custom_data
 478
 479     \%all_data = $object->custom_data;
 480     $object->custom_data(\%all_data);
 481
 482     \%data = $object->custom_data($key);
 483     $object->custom_data($key => \%data);
 484     $object->custom_data(%data);
 485     $object->custom_data(key => $value, %data);
 486
 487 Get and set custom data. Custom data is metadata associated with an object.
 488
 489 Each data item can have a few attributes associated with it.
 490
 491 =for :list
 492 * C<key> - A unique text string identifier used to look up the data item (required)
 493 * C<value> - A text string value (required)
 494 * C<last_modification_time> (optional, KDBX4.1+)
 495
 496 =cut
 497
 498 sub custom_data {
 499     my $self = shift;
 500     $self->{custom_data} = shift if @_ == 1 && is_plain_hashref($_[0]);
 501     return $self->{custom_data} //= {} if !@_;
 502
 503     my %args = @_     == 2 ? (key => shift, value => shift)
 504              : @_ % 2 == 1 ? (key => shift, @_) : @_;
 505
 506     if (!$args{key} && !$args{value}) {
 507         my %standard = (key => 1, value => 1, last_modification_time => 1);
 508         my @other_keys = grep { !$standard{$_} } keys %args;
 509         if (@other_keys == 1) {
 510             my $key = $args{key} = $other_keys[0];
 511             $args{value} = delete $args{$key};
 512         }
 513     }
 514
 515     my $key = $args{key} or throw 'Must provide a custom_data key to access';
 516
 517     return $self->{custom_data}{$key} = $args{value} if is_plain_hashref($args{value});
 518
 519     while (my ($field, $value) = each %args) {
 520         $self->{custom_data}{$key}{$field} = $value;
 521     }
 522     return $self->{custom_data}{$key};
 523 }
 524
 525 =method custom_data_value
 526
 527     $value = $object->custom_data_value($key);
 528
 529 Exactly the same as L</custom_data> except returns just the custom data's value rather than a structure of
 530 attributes. This is a shortcut for:
 531
 532     my $data = $object->custom_data($key);
 533     my $value = defined $data ? $data->{value} : undef;
 534
 535 =cut
 536
 537 sub custom_data_value {
 538     my $self = shift;
 539     my $data = $self->custom_data(@_) // return undef;
 540     return $data->{value};
 541 }
 542
 543 ##############################################################################
 544
 545 =method begin_work
 546
 547     $txn = $object->begin_work(%options);
 548     $object->begin_work(%options);
 549
 550 Begin a new transaction. Returns a L<File::KDBX::Transaction> object that can be scoped to ensure a rollback
 551 occurs if exceptions are thrown. Alternatively, if called in void context, there will be no
 552 B<File::KDBX::Transaction> and it is instead your responsibility to call L</commit> or L</rollback> as
 553 appropriate. It is undefined behavior to call these if a B<File::KDBX::Transaction> exists. Recursive
 554 transactions are allowed.
 555
 556 Signals created during a transaction are delayed until all transactions are resolved. If the outermost
 557 transaction is committed, then the signals are de-duplicated and delivered. Otherwise the signals are dropped.
 558 This means that the KDBX database will not fix broken references or mark itself dirty until after the
 559 transaction is committed.
 560
 561 How it works: With the beginning of a transaction, a snapshot of the object is created. In the event of
 562 a rollback, the object's data is replaced with data from the snapshot.
 563
 564 By default, the snapshot is shallow (i.e. does not include subroups, entries or historical entries). This
 565 means that only modifications to the object itself (its data, fields, strings, etc.) are atomic; modifications
 566 to subroups etc., including adding or removing items, are auto-committed instantly and will persist regardless
 567 of the result of the pending transaction. You can override this for groups, entries and history independently
 568 using options:
 569
 570 =for :list
 571 * C<entries> - If set, snapshot entries within a group, deeply (default: false)
 572 * C<groups> - If set, snapshot subroups within a group, deeply (default: false)
 573 * C<history> - If set, snapshot historical entries within an entry (default: false)
 574
 575 For example, if you begin a transaction on a group object using the C<entries> option, like this:
 576
 577     $group->begin_work(entries => 1);
 578
 579 Then if you modify any of the group's entries OR add new entries OR delete entries, all of that will be undone
 580 if the transaction is rolled back. With a default-configured transaction, however, changes to entries are kept
 581 even if the transaction is rolled back.
 582
 583 =cut
 584
 585 sub begin_work {
 586     my $self = shift;
 587
 588     if (defined wantarray) {
 589         require File::KDBX::Transaction;
 590         return File::KDBX::Transaction->new($self, @_);
 591     }
 592
 593     my %args = @_;
 594     my $orig = $args{snapshot} // do {
 595         my $c = $self->clone(
 596             entries => $args{entries} // 0,
 597             groups  => $args{groups}  // 0,
 598             history => $args{history} // 0,
 599         );
 600         $c->{entries} = $self->{entries} if !$args{entries};
 601         $c->{groups}  = $self->{groups}  if !$args{groups};
 602         $c->{history} = $self->{history} if !$args{history};
 603         $c;
 604     };
 605
 606     my $id = Hash::Util::FieldHash::id($orig);
 607     _save_references($id, $self, $orig);
 608
 609     $self->_signal_begin_work;
 610
 611     push @{$self->_txns}, $orig;
 612 }
 613
 614 =method commit
 615
 616     $object->commit;
 617
 618 Commit a transaction, making updates to C<$object> permanent. Returns itself to allow method chaining.
 619
 620 =cut
 621
 622 sub commit {
 623     my $self = shift;
 624     my $orig = pop @{$self->_txns} or return $self;
 625     $self->_commit($orig);
 626     my $signals = $self->_signal_commit;
 627     $self->_signal_send($signals) if !$self->_in_txn;
 628     return $self;
 629 }
 630
 631 =method rollback
 632
 633     $object->rollback;
 634
 635 Roll back the most recent transaction, throwing away any updates to the L</object> made since the transaction
 636 began. Returns itself to allow method chaining.
 637
 638 =cut
 639
 640 sub rollback {
 641     my $self = shift;
 642
 643     my $orig = pop @{$self->_txns} or return $self;
 644
 645     my $id = Hash::Util::FieldHash::id($orig);
 646     _restore_references($id, $orig);
 647
 648     $self->_signal_rollback;
 649
 650     return $self;
 651 }
 652
 653 # Get whether or not there is at least one pending transaction.
 654 sub _in_txn { scalar @{$_[0]->_txns} }
 655
 656 # Get an array ref of pending transactions.
 657 sub _txns   { $TXNS{$_[0]} //= [] }
 658
 659 # The _commit hook notifies subclasses that a commit has occurred.
 660 sub _commit { die 'Not implemented' }
 661
 662 # Get a reference to an object that represents an object's committed state. If there is no pending
 663 # transaction, this is just $self. If there is a transaction, this is the snapshot take before the transaction
 664 # began. This method is private because it provides direct access to the actual snapshot. It is important that
 665 # the snapshot not be changed or a rollback would roll back to an altered state.
 666 # This is used by File::KDBX::Dumper::XML so as to not dump uncommitted changes.
 667 sub _committed {
 668     my $self = shift;
 669     my ($orig) = @{$self->_txns};
 670     return $orig // $self;
 671 }
 672
 673 # In addition to cloning an object when beginning work, we also keep track its hashrefs and arrayrefs
 674 # internally so that we can restore to the very same structures in the case of a rollback.
 675 sub _save_references {
 676     my $id   = shift;
 677     my $self = shift;
 678     my $orig = shift;
 679
 680     if (is_plain_arrayref($orig)) {
 681         for (my $i = 0; $i < @$orig; ++$i) {
 682             _save_references($id, $self->[$i], $orig->[$i]);
 683         }
 684         $REFS{$id}{Hash::Util::FieldHash::id($orig)} = $self;
 685     }
 686     elsif (is_plain_hashref($orig) || (blessed $orig && $orig->isa(__PACKAGE__))) {
 687         for my $key (keys %$orig) {
 688             _save_references($id, $self->{$key}, $orig->{$key});
 689         }
 690         $REFS{$id}{Hash::Util::FieldHash::id($orig)} = $self;
 691     }
 692 }
 693
 694 # During a rollback, copy data from the snapshot back into the original internal structures.
 695 sub _restore_references {
 696     my $id   = shift;
 697     my $orig = shift // return;
 698     my $self = delete $REFS{$id}{Hash::Util::FieldHash::id($orig) // ''} // return $orig;
 699
 700     if (is_plain_arrayref($orig)) {
 701         @$self = map { _restore_references($id, $_) } @$orig;
 702     }
 703     elsif (is_plain_hashref($orig) || (blessed $orig && $orig->isa(__PACKAGE__))) {
 704         for my $key (keys %$orig) {
 705             # next if is_ref($orig->{$key}) &&
 706             #     (Hash::Util::FieldHash::id($self->{$key}) // 0) == Hash::Util::FieldHash::id($orig->{$key});
 707             $self->{$key} = _restore_references($id, $orig->{$key});
 708         }
 709     }
 710
 711     return $self;
 712 }
 713
 714 ##############################################################################
 715
 716 sub _signal {
 717     my $self = shift;
 718     my $type = shift;
 719
 720     if ($self->_in_txn) {
 721         my $stack = $self->_signal_stack;
 722         my $queue = $stack->[-1];
 723         push @$queue, [$type, @_];
 724     }
 725
 726     $self->_signal_send([[$type, @_]]);
 727
 728     return $self;
 729 }
 730
 731 sub _signal_stack { $SIGNALS{$_[0]} //= [] }
 732
 733 sub _signal_begin_work {
 734     my $self = shift;
 735     push @{$self->_signal_stack}, [];
 736 }
 737
 738 sub _signal_commit {
 739     my $self = shift;
 740     my $signals = pop @{$self->_signal_stack};
 741     my $previous = $self->_signal_stack->[-1] // [];
 742     push @$previous, @$signals;
 743     return $previous;
 744 }
 745
 746 sub _signal_rollback {
 747     my $self = shift;
 748     pop @{$self->_signal_stack};
 749 }
 750
 751 sub _signal_send {
 752     my $self    = shift;
 753     my $signals = shift // [];
 754
 755     my $kdbx = $KDBX{$self} or return;
 756
 757     # de-duplicate, keeping the most recent signal for each type
 758     my %seen;
 759     my @signals = grep { !$seen{$_->[0]}++ } reverse @$signals;
 760
 761     for my $sig (reverse @signals) {
 762         $kdbx->_handle_signal($self, @$sig);
 763     }
 764 }
 765
 766 ##############################################################################
 767
 768 sub _wrap_group {
 769     my $self  = shift;
 770     my $group = shift;
 771     require File::KDBX::Group;
 772     return File::KDBX::Group->wrap($group, $KDBX{$self});
 773 }
 774
 775 sub _wrap_entry {
 776     my $self  = shift;
 777     my $entry = shift;
 778     require File::KDBX::Entry;
 779     return File::KDBX::Entry->wrap($entry, $KDBX{$self});
 780 }
 781
 782 sub TO_JSON { +{%{$_[0]}} }
 783
 784 1;
 785 __END__
 786
 787 =for Pod::Coverage STORABLE_freeze STORABLE_thaw TO_JSON
 788
 789 =head1 DESCRIPTION
 790
 791 KDBX is an object database. This abstract class represents an object. You should not use this class directly
 792 but instead use its subclasses:
 793
 794 =for :list
 795 * L<File::KDBX::Entry>
 796 * L<File::KDBX::Group>
 797
 798 There is some functionality shared by both types of objects, and that's what this class provides.
 799
 800 Each object can be connected with a L<File::KDBX> database or be disconnected. A disconnected object exists in
 801 memory but will not be persisted when dumping a database. It is also possible for an object to be connected
 802 with a database but not be part of the object tree (i.e. is not the root group or any subroup or entry).
 803 A disconnected object or an object not part of the object tree of a database can be added to a database using
 804 one of:
 805
 806 =for :list
 807 * L<File::KDBX/add_entry>
 808 * L<File::KDBX/add_group>
 809 * L<File::KDBX::Group/add_entry>
 810 * L<File::KDBX::Group/add_group>
 811 * L<File::KDBX::Entry/add_historical_entry>
 812
 813 It is possible to copy or move objects between databases, but B<DO NOT> include the same object in more
 814 than one database at once or there could be some strange aliasing effects (i.e. changes in one database might
 815 effect another in unexpected ways). This could lead to difficult-to-debug problems. It is similarly not safe
 816 or valid to add the same object multiple times to the same database. For example:
 817
 818     my $entry = File::KDBX::Entry->(title => 'Whatever');
 819
 820     # DO NOT DO THIS:
 821     $kdbx->add_entry($entry);
 822     $another_kdbx->add_entry($entry);
 823
 824     # DO NOT DO THIS:
 825     $kdbx->add_entry($entry);
 826     $kdbx->add_entry($entry); # again
 827
 828 Instead, do this:
 829
 830     # Copy an entry to multiple databases:
 831     $kdbx->add_entry($entry);
 832     $another_kdbx->add_entry($entry->clone);
 833
 834     # OR move an existing entry from one database to another:
 835     $another_kdbx->add_entry($entry->remove);
 836
 837 =cut